README

这个包装器允许您与Clockwork交互，而无需创建任何XML或进行HTTP调用。这个版本的包装器已经被分叉并更新，以支持Rock & Scissor的新版PHP，因为MediaBurst被Textanywhere收购，这意味着原始仓库已被放弃。我们打算只要Textanywhere仍然支持API，就会保持这个包的更新。

什么是Clockwork？

Clockwork 是 Mediaburst的短信API。

先决条件

一个 Clockwork 账户

用法

使用composer安装

获取Clockwork的最简单方法是通过 Composer 自动下载并将其包含到您的项目中。设置 Composer 并将其添加到您的 composer.json 中

{
    "require": {
        "rockandscissor/clockworksms": "2.0.*"
    }
}

如果您正在使用自己的自动加载器，我们使用PSR-4命名空间方案。

直接包含

下载Clockwork库，将其放入您的项目，并要求Clockwork类和ClockworkException类

require 'src/Clockwork.php';
require 'src/ClockworkException.php';

发送消息

$clockwork = new mediaburst\ClockworkSMS\Clockwork( $API_KEY ); //Be careful not to post your API Keys to public repositories.
$message = array( 'to' => '441234567891', 'message' => 'This is a test!' );
$result = $clockwork->send( $message );

发送多条消息

我们建议您使用500条消息或更少的批量大小。通过限制批量大小，可以防止发送时出现超时。

$clockwork = new mediaburst\ClockworkSMS\Clockwork( $API_KEY ); //Be careful not to post your API Keys to public repositories.
$messages = array(
    array( 'to' => '441234567891', 'message' => 'This is a test!' ),
    array( 'to' => '441234567892', 'message' => 'This is a test 2!' )
);
$results = $clockwork->send( $messages );

处理响应

响应以数组的形式返回，其中包含唯一的Clockwork消息ID，消息是否成功（success），以及原始短信，以便您可以更新数据库。

Array
(
    [id] => VE_164732148
    [success] => 1
    [sms] => Array
        (
            [to] => 441234567891
            [message] => This is a test!
        )

)

如果您在单个发送中发送多条短信，您将得到一个结果数组，每条短信一个结果。

结果看起来可能像这样

Array
(
    [0] => Array
        (
            [id] => VI_143228951
            [success] => 1
            [sms] => Array
                (
                    [to] => 441234567891
                    [message] => This is a test!
                )

        )

    [1] => Array
        (
            [id] => VI_143228952
            [success] => 1
            [sms] => Array
                (
                    [to] => 441234567892
                    [message] => This is a test 2!
                )

        )

)

如果消息失败，失败原因将在 error_code 和 error_message 中设置。

例如，如果您向无效的手机号码 "abc" 发送短信

Array
(
    [error_code] => 10
    [error_message] => Invalid 'To' Parameter
    [success] => 0
    [sms] => Array
        (
            [to] => abc
            [message] => This is a test!
        )

)

检查余额

检查您的可用短信余额

$clockwork = new mediaburst\ClockworkSMS\Clockwork( $API_KEY ); //Be careful not to post your API Keys to public repositories.
$clockwork->checkBalance();

这将返回

Array
(
    [symbol] => £
    [balance] => 351.91
    [code] => GBP
    [account_type] => PAYG
)

账户类型可以是预付费或发票。

处理错误

如果整个调用失败，Clockwork包装器将抛出 ClockworkException。

try
{
    $clockwork = new rockandscissor\ClockworkSMS\Clockwork( 'invalid_key' );
    $message = array( 'to' => 'abc', 'message' => 'This is a test!' );
    $result = $clockwork->send( $message );
}
catch( mediaburst\ClockworkSMS\ClockworkException $e )
{
    print $e->getMessage();
    // Invalid API Key
}

高级用法

这个类有一些额外的功能，一些用户可能觉得很有用，如果没有设置，将使用账户默认值。

可选参数

有关这些选项的完整详细信息，请参阅 Clockwork 文档。

$from [字符串]

当手机收到消息时显示的发件人地址
$long [布尔值]

启用长短信。标准短信可以包含160个字符，长短信支持最多459个字符。
$truncate [可以为null的布尔值]

如果消息太长，则截断消息负载，如果此设置为false，则消息太长时会失败。
$invalid_char_action [字符串]

如果消息包含无效字符时将执行什么操作。可能的值包括
- error - 失败消息
- remove - 删除无效字符然后发送
- replace - 替换一些常见的无效字符，例如将曲线引号替换为直引号
$ssl [布尔值，默认：true]

在向Clockwork API发起HTTP请求时使用SSL

设置选项

全局选项

在API对象上设置的选项将适用于所有短信消息，除非特别覆盖。

在这个例子中，两条消息都将由Clockwork发送。

$options = array( 'from' => 'Clockwork' );
$clockwork = new mediaburst\ClockworkSMS\Clockwork( $API_KEY, $options ); //Be careful not to post your API Keys to public repositories.
$messages = array(
    array( 'to' => '441234567891', 'message' => 'This is a test!' ),
    array( 'to' => '441234567892', 'message' => 'This is a test 2!' )
);
$results = $clockwork->send( $messages );

每条消息的选项

为每条消息单独设置选项值。

在这个例子中，一条消息将来自Clockwork，另一条来自84433。

$clockwork = new mediaburst\ClockworkSMS\Clockwork( $API_KEY, $options ); //Be careful not to post your API Keys to public repositories.
$messages = array(
    array( 'to' => '441234567891', 'message' => 'This is a test!', 'from' => 'Clockwork' ),
    array( 'to' => '441234567892', 'message' => 'This is a test 2!', 'from' => '84433' )
);
$results = $clockwork->send( $messages );

SSL错误

由于PHP配置的多样性，一小部分用户在调用API时可能会因为SSL配置问题而遇到PHP错误。

错误通常会看起来像这样

Fatal error:
Uncaught exception 'Exception' with message 'HTTP Error calling Clockwork API
HTTP Status: 0
cURL Erorr: SSL certificate problem, verify that the CA cert is OK.
Details: error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed'

如果您看到这个错误，有两种修复方法，第一种很简单，只需在Clockwork调用中禁用SSL。或者，您可以设置带有正确根证书的PHP安装。

在Clockwork调用中禁用SSL

$options = array( 'ssl' => false );
$clockwork = new mediaburst\ClockworkSMS\Clockwork( $API_KEY, $options );  //Be careful not to post your API Keys to public repositories.

在您的服务器上设置SSL根证书

这要复杂得多，因为它取决于您的配置，但是网上有许多可用的指南。尝试搜索“windows php curl root certificates”或“ubuntu update root certificates”。

许可证

本项目采用MIT开源许可证。

此许可证的副本可以在license.txt中找到。

贡献

如果您对这款包装有任何反馈，请给我们发电子邮件至 hello@clockworksms.com。

该项目托管在GitHub上，网址为 https://github.com/mediaburst/clockwork-php。如果您想贡献错误修复或改进，请复制该项目并提交拉取请求。

rockandscissor / clockworksms

维护者

详情