cmtelecom / messaging-php
Requires
- php: >=5.4.0
- guzzlehttp/psr7: 1.6.*
- myclabs/php-enum: 1.5.*
- php-http/httplug: 2.1.*
Requires (Dev)
- fzaninotto/faker: 1.6.*
- php-http/mock-client: 1.3.*
- phpunit/phpunit: ^8.5
Suggests
- php-http/guzzle6-adapter: This is the default and recommended http client adapter. A http client adapter is required!
This package is auto-updated.
Last update: 2020-01-09 15:06:09 UTC
README
注意:该项目不再维护。请使用 https://github.com/cmdotcom/text-sdk-php 代替。
PHP SDK,用于轻松使用CM消息服务。使用简单的语法构建您的短信、推送和/或语音消息,并通过CM服务直接发送。
简单示例
require('vendor/autoload.php'); use GuzzleHttp\Client as GuzzleClient; use Http\Adapter\Guzzle6\Client as GuzzleAdapter; $message = (new \CM\Messaging\Message()) ->setFrom('Your name/company name') ->setTo(['0031612345678', '0031623456789', '0031634567890']) ->setBody('Your message'); try { $adapter = new GuzzleAdapter(new GuzzleClient()); $client = new \CM\Messaging\Client($adapter, 'your-product-token'); $result = $client->send($message); if($result->isAccepted()){ // All messages were accepted } else { // Not all messages were accepted } } catch (\CM\Messaging\Exception\BadRequestException $e) { // The request failed because of an invalid value, all messages has not been send } catch (\Http\Client\Exception\TransferException $e) { // Something unexpected happened }
要求
- 拥有积分的CM账户,您可以在此处注册。
- 已安装Composer,或手动加载
- PHP >= 7.2
安装
在项目根目录中运行以下命令,将CM消息SDK添加到项目依赖项
composer require cmtelecom/messaging-php
并且
composer require php-http/guzzle6-adapter
*当使用替代HttpClient时,您无需添加Guzzle适配器依赖项,但建议使用Guzzle。对于高级使用和其他HTTP客户端,您可以查看http://docs.php-http.org/en/latest/clients.html。
用法
使用您的 产品令牌
实例化客户端,该令牌可在您登录到 https://gateway.cmtelecom.com 时的网关应用程序中找到。
$client = new \CM\Messaging\Client('your-product-token');
构建消息
要创建消息,您可以使用一行简单的代码。所需的属性是 from
、to
和 body
。所有其他属性均可选。
use \CM\Messaging\Settings\AllowedChannel; $message = (new \CM\Messaging\Message()) ->setFrom('Your name/company name') ->setTo(['0031612345678', '0031623456789', '0031634567890']) ->setBody('Message') ->setReference('Your message') ->setAllowedChannels([AllowedChannel::SMS, AllowedChannel::PUSH, AllowedChannel::VOICE]) ->setAppKey('your-app-key') ->setMinimumNumberOfMessageParts(1) ->setMaximumNumberOfMessageParts(8) ->setDcs(8);
发送消息
在构建消息后,您可以按照以下方式发送。
$message = (new \CM\Messaging\Message()) ->setFrom('Your name/company name') ->setTo(['0031612345678']) ->setBody('Message body'); try { $adapter = new GuzzleAdapter(new GuzzleClient()); $client = new \CM\Messaging\Client($adapter, 'your-product-token'); $result = $client->send($message); } catch (\CM\Messaging\Exception\BadRequestException $e) { // The request failed because of an invalid value, all messages has not been send } catch (\Http\Client\Exception\TransferException $e) { // Something unexpected happened }
发送一批消息
当您发送一批消息时,这是您有多种不同内容的消息时。您可以通过创建消息数组在一次请求中发送所有这些消息。如果所有接收者的内容相同,您只需在 setTo()
中添加接收者电话号码数组,在这种情况下您不需要创建多个消息(如简单示例所示)。
$message_1 = (new \CM\Messaging\Message()) ->setFrom('Your name/company name') ->setTo(['0031612345678']) ->setBody('Message one'); $messages[] = $message_1; $message_2 = (new \CM\Messaging\Message()) ->setFrom('Your name/company name') ->setTo(['0031623456789', '0031634567890']) ->setBody('Message two'); $messages[] = $message_2; try { $adapter = new GuzzleAdapter(new GuzzleClient()); $client = new \CM\Messaging\Client($adapter, 'your-product-token'); $result = $client->send($messages); } catch (\CM\Messaging\Exception\BadRequestException $e) { // The request failed because of an invalid value, all messages has not been send } catch (\Http\Client\Exception\TransferException $e) { // Something unexpected happened }
处理响应
在发送消息后,您将收到一个包含已接受和失败消息的响应。这样,您可以验证消息是否按预期处理。您可以为所有消息执行此操作,或者可选地添加电话号码或电话号码数组以检查特定消息。
try { $result = $client->send($messages); // returns true if all messages are accepted $result->isAccepted() // returns true if all messages are failed $result->isFailed() // returns an array with the accepted message responses $result->getAccepted() // returns an array with the failed message responses $result->getFailed() } catch (\CM\Messaging\Exception\BadRequestException $e) { // The request failed because of an invalid value, all messages has not been send // Returns body contents of the response with detailed error message(s) $contents = $e->getResponse()->getBody()->getContents()); } catch (\Http\Client\Exception\TransferException $e) { // Something unexpected happened }
为了更详细的错误处理,您可以可选地捕获 RequestException
、HttpException
和/或 NetworkException
,这些都是 TransferException
异常的子类。
还可以检索 PSR-7 响应,这可以通过 getResponse()
完成。响应体内容可以通过 getResponse()->getBody()->getContents()
获取。
高级用法
默认属性
如果您多次调用 $client->send()
方法,并且希望为应用中发送的所有消息设置某些属性,您可以在 $client
上设置这些属性。在 Message
中设置的属性将覆盖 $client
中设置的属性。
$client = (new \CM\Messaging\Client('your-product-token')) ->setReference('Your reference') ->setAllowedChannels([AllowedChannel::SMS, AllowedChannel::PUSH, AllowedChannel::VOICE]) ->setAppKey('your-app-key') ->setMinimumNumberOfMessageParts(1) ->setMaximumNumberOfMessageParts(8) ->setDcs(8);
策略
默认情况下,此 SDK 会移除同一消息中的重复电话号码,因为这假定您不希望同时向同一电话号码发送完全相同的信息两次。如果您想禁用此策略/行为,您可以在 send()
方法中添加以下内容。
$client->send($messages, ['strategy' => ['keep_duplicate_phone_numbers']]);
配置异常
抛出异常 | 描述 |
---|---|
InvalidConfigurationException | 配置无效 |
└ InvalidAllowedChannelException | 一个或多个允许的频道不是有效选项 |
└ InvalidStrategyException | 一个或多个策略不是有效选项 |
HTTP 异常
状态码 | 抛出异常 | 描述 |
---|---|---|
null | TransferException | 发生了意外情况 |
└ null | RequestException | 请求无效 |
└ 400-499 | HttpException | 客户端错误 |
└ 400 | BadRequestException | 请求失败,因为值无效,未发送所有消息 |
└ 500-599 | NetworkException | 服务器端错误 |
方法
客户端
方法 | 参数 | 返回 |
---|---|---|
__construct() | $productToken, HttpClient $httpClient | void |
send() | array/Message $messages, array/null $parameters | Response |
getBodyType() | BodyType | |
setBodyType() | BodyType $bodyType | $this |
getDcs() | int | |
setDcs() | int $dcs | $this |
getReference() | string | |
setReference() | string $reference | $this |
getCustomGrouping1() | string | |
setCustomGrouping1() | string $reference | $this |
getCustomGrouping2() | string | |
setCustomGrouping2() | string $reference | $this |
getCustomGrouping3() | string | |
setCustomGrouping3() | string $reference | $this |
getMinimumNumberOfMessageParts() | int | |
setMinimumNumberOfMessageParts() | int $minimumNumberOfMessageParts | $this |
getMaximumNumberOfMessageParts() | int | |
setMaximumNumberOfMessageParts() | int $minimumNumberOfMessageParts | $this |
getAppKey() | string | |
setAppKey() | string $appKey | $this |
getAllowedChannels() | array | |
setAllowedChannels() | array/AllowedChannel $allowedChannels | $this |
getProductToken() | string |
消息
方法 | 参数 | 返回 |
---|---|---|
getFrom() | array | |
setFrom() | string $from | $this |
getTo() | array | |
setTo() | array/string $to | $this |
getBody() | string | |
setBody() | string $body, BodyType/null $bodyType | $this |
getDcs() | int | |
setDcs() | int $dcs | $this |
getReference() | string | |
setReference() | string $reference | $this |
getCustomGrouping1() | string | |
setCustomGrouping1() | string $reference | $this |
getCustomGrouping2() | string | |
setCustomGrouping2() | string $reference | $this |
getCustomGrouping3() | string | |
setCustomGrouping3() | string $reference | $this |
getMinimumNumberOfMessageParts() | int | |
setMinimumNumberOfMessageParts() | int $minimumNumberOfMessageParts | $this |
getMaximumNumberOfMessageParts() | int | |
setMaximumNumberOfMessageParts() | int $minimumNumberOfMessageParts | $this |
getAppKey() | string | |
setAppKey() | string $appKey | $this |
getAllowedChannels() | array | |
setAllowedChannels() | array/AllowedChannel $allowedChannels | $this |
getProductToken() | string |
响应
方法 | 参数 | 返回 |
---|---|---|
getDetails() | string | |
getAccepted() | array/string/null $phoneNumbers | array /null |
isAccepted() | array/string/null $phoneNumbers | bool |
getFailed() | array/string/null $phoneNumbers | array/null |
isFailed() | array/string/null $phoneNumbers | bool |
getResponse() | PSR-7 Response |
待办事项
- 自定义分组支持