README

这个包装器允许您无需创建任何XML或进行HTTP调用即可与Clockwork交互。

什么是Clockwork？

Clockwork是 Mediaburst的 SMS API。

先决条件

一个Clockwork账户

使用方法

使用Composer安装

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

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

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

直接包含

下载Clockwork库，将其放在您的项目中，并require 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
)

账户类型可以是PAYG或发票。

处理错误

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

try 
{
    $clockwork = new mediaburst\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 [可空布尔值]

如果消息负载太长，则截断消息，如果此设置为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。如果您想贡献错误修复或改进，请将该项目的分支提交为pull request。

mediaburst / clockworksms

维护者

详细信息