cmtelecom/messaging-php

此包已被弃用且不再维护。作者建议使用 cmdotcom/text-sdk-php 包。

用于与CM平台集成的PHP客户端

v2.0.0 2020-01-09 13:18 UTC

This package is auto-updated.

Last update: 2020-01-09 15:06:09 UTC


README

Packagist Packagist Travis

注意:该项目不再维护。请使用 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');

构建消息

要创建消息,您可以使用一行简单的代码。所需的属性是 fromtobody。所有其他属性均可选。

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
}

为了更详细的错误处理,您可以可选地捕获 RequestExceptionHttpException 和/或 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

待办事项

  • 自定义分组支持