easy-sms

Easy SMS

:calling: 一款多渠道的短信发送组件

## 特点 1. 支持目前市面多家服务商 1. 一套写法兼容所有平台 1. 简单配置即可灵活增减服务商 1. 内置多种服务商轮询策略、支持自定义轮询策略 1. 统一的返回值格式，便于日志与监控 1. 自动轮询选择可用的服务商 1. 更多等你去发现与改进... ## 平台支持 - [腾讯云 SMS](https://cloud.tencent.com/product/sms) - [Ucloud](https://www.ucloud.cn) - [七牛云](https://www.qiniu.com/) - [SendCloud](http://www.sendcloud.net/) - [阿里云](https://www.aliyun.com/) - [云片](https://www.yunpian.com) - [Submail](https://www.mysubmail.com) - [螺丝帽](https://luosimao.com/) - [容联云通讯](http://www.yuntongxun.com) - [互亿无线](http://www.ihuyi.com) - [聚合数据](https://www.juhe.cn) - [百度云](https://cloud.baidu.com/) - [华信短信平台](http://www.ipyy.com/) - [253云通讯（创蓝）](https://www.253.com/) - [创蓝云智](https://www.chuanglan.com/) - [融云](http://www.rongcloud.cn) - [天毅无线](http://www.85hu.com/) - [华为云](https://www.huaweicloud.com/product/msgsms.html) - [网易云信](https://yunxin.163.com/sms) - [云之讯](https://www.ucpaas.com/index.html) - [凯信通](http://www.kingtto.cn/) - [UE35.net](http://uesms.ue35.cn/) - [短信宝](http://www.smsbao.com/) - [Tiniyo](https://tiniyo.com/) - [摩杜云](https://www.moduyun.com/) - [融合云（助通）](https://www.ztinfo.cn/products/sms) - [蜘蛛云](https://zzyun.com/) - [融合云信](https://maap.wo.cn/) - [天瑞云](http://cms.tinree.com/) - [时代互联](https://www.now.cn/) - [火山引擎](https://console.volcengine.com/sms/) - [移动云MAS（黑名单模式）](https://mas.10086.cn) - [电信天翼云](https://www.ctyun.cn/document/10020426/10021544) - [微趣云](https://sms.weiqucloud.com/) - [秒信短信平台](http://www.51miaoxin.com) ## 环境需求 - PHP >= 8.4 ## 安装 ```shell composer require "overtrue/easy-sms" ``` **For Laravel notification** 如果你喜欢使用 [Laravel Notification](https://laravel.com/docs/5.8/notifications), 可以考虑直接使用朋友封装的拓展包： ## 使用 ``` … ``` ## 短信内容 由于使用多网关发送，所以一条短信要支持多平台发送，每家的发送方式不一样，但是我们抽象定义了以下公用属性： - `content` 文字内容，使用在像云片类似的以文字内容发送的平台 - `template` 模板 ID，使用在以模板ID来发送短信的平台 - `data` 模板变量，使用在以模板ID来发送短信的平台 所以，在使用过程中你可以根据所要使用的平台定义发送的内容。 ```php $easySms->send(13188888888, [ 'content' => '您的验证码为: 6379', 'template' => 'SMS_001', 'data' => [ 'code' => 6379 ], ]); ``` 你也可以使用闭包来返回对应的值： ```php $easySms->send(13188888888, [ 'content' => function($gateway){ return '您的验证码为: 6379'; }, 'template' => function($gateway){ return 'SMS_001'; }, 'data' => function($gateway){ return [ 'code' => 6379 ]; }, ]); ``` 你可以根据 `$gateway` 参数类型来判断返回值，例如： ```php $easySms->send(13188888888, [ 'content' => function($gateway){ if ($gateway->getName() == 'yunpian') { return '云片专用验证码：1235'; } return '您的验证码为: 6379'; }, 'template' => function($gateway){ if ($gateway->getName() == 'aliyun') { return 'TP2818'; } return 'SMS_001'; }, 'data' => function($gateway){ return [ 'code' => 6379 ]; }, ]); ``` ## 发送网关 默认使用 `default` 中的设置来发送，如果某一条短信你想要覆盖默认的设置。在 `send` 方法中使用第三个参数即可： ```php $easySms->send(13188888888, [ 'content' => '您的验证码为: 6379', 'template' => 'SMS_001', 'data' => [ 'code' => 6379 ], ], ['yunpian', 'juhe']); // 这里的网关配置将会覆盖全局默认值 ``` ## 返回值 由于使用多网关发送，所以返回值为一个数组，结构如下： ```php [ 'yunpian' => [ 'gateway' => 'yunpian', 'status' => 'success', 'result' => [...] // 平台返回值 ], 'juhe' => [ 'gateway' => 'juhe', 'status' => 'failure', 'exception' => \Overtrue\EasySms\Exceptions\GatewayErrorException 对象 ], //... ] ``` 如果所选网关列表均发送失败时，将会抛出 `Overtrue\EasySms\Exceptions\NoGatewayAvailableException` 异常，你可以使用 `$e->results` 获取发送结果。 你也可以使用 `$e` 提供的更多便捷方法： ```php $e->getResults(); // 返回所有 API 的结果，结构同上 $e->getExceptions(); // 返回所有调用异常列表 $e->getException($gateway); // 返回指定网关名称的异常对象 $e->getLastException(); // 获取最后一个失败的异常对象 ``` ## 自定义网关 本拓展已经支持用户自定义网关，你可以很方便的配置即可当成与其它拓展一样的使用： ```php $config = [ ... 'default' => [ 'gateways' => [ 'mygateway', // 配置你的网站到可用的网关列表 ], ], 'gateways' => [ 'mygateway' => [...], // 你网关所需要的参数，如果没有可以不配置 ], ]; $easySms = new EasySms($config); // 注册 $easySms->extend('mygateway', function($gatewayConfig){ // $gatewayConfig 来自配置文件里的 `gateways.mygateway` return new MyGateway($gatewayConfig); }); $easySms->send(13188888888, [ 'content' => '您的验证码为: 6379', 'template' => 'SMS_001', 'data' => [ 'code' => 6379 ], ]); ``` ## 国际短信 国际短信与国内短信的区别是号码前面需要加国际码，但是由于各平台对国际号码的写法不一致，所以在发送国际短信的时候有一点区别： ```php use Overtrue\EasySms\PhoneNumber; // 发送到国际码为 31 的国际号码 $number = new PhoneNumber(13188888888, 31); $easySms->send($number, [ 'content' => '您的验证码为: 6379', 'template' => 'SMS_001', 'data' => [ 'code' => 6379 ], ]); ``` ## 定义短信 你可以根据发送场景的不同，定义不同的短信类，从而实现一处定义多处调用，你可以继承 `Overtrue\EasySms\Message` 来定义短信模型： ``` … ``` > 更多自定义方式请参考：[`Overtrue\EasySms\Message`](Overtrue\EasySms\Message;) 发送自定义短信： ```php $order = ...; $message = new OrderPaidMessage($order); $easySms->send(13188888888, $message); ``` ## 各平台配置说明 ### [阿里云](https://www.aliyun.com/) 短信内容使用 `template` + `data` ```php 'aliyun' => [ 'access_key_id' => '', 'access_key_secret' => '', 'sign_name' => '', ], ``` ### [阿里云Rest](https://www.aliyun.com/) 短信内容使用 `template` + `data` ```php 'aliyunrest' => [ 'app_key' => '', 'app_secret_key' => '', 'sign_name' => '', ], ``` ### [阿里云国际](https://www.alibabacloud.com/help/zh/doc-detail/160524.html) 短信内容使用 `template` + `data` ```php 'aliyunintl' => [ 'access_key_id' => '', 'access_key_secret' => '', 'sign_name' => '', ], ``` 发送示例： ```php use Overtrue\EasySms\PhoneNumber; $easySms = new EasySms($config); $phone_number = new PhoneNumber(18888888888, 86); $easySms->send($phone_number, [ 'content' => '您好：先生/女士！您的验证码为${code}，有效时间是5分钟，请及时验证。', 'template' => 'SMS_00000001', // 模板ID 'data' => [ "code" => 521410, ], ]); ``` ### [阿里云短信认证](https://help.aliyun.com/zh/pnvs/getting-started/sms-authentication-service-novice-guide) 短信内容使用 `template` + `data` ```php 'aliyundypns' => [ 'access_key_id' => '', 'access_key_secret' => '', 'sign_name' => '', // 不可自定义，可选：速通互联验证码、云渚科技验证服务等 ], ``` 发送示例： ```php $easySms = new EasySms($config); $easySms->send('18888888888', [ 'template' => '100001', // 模板ID，详见：https://dypns.console.aliyun.com/smsCertParamsConfig 'data' => [ "code" => 1234, "min" => 5, // 有效时间（分钟） ], ]); ``` ### [云片](https://www.yunpian.com) 短信内容使用 `content` ```php 'yunpian' => [ 'api_key' => '', 'signature' => '【默认签名】', // 内容中无签名时使用 ], ``` ### [Submail](https://www.mysubmail.com) 短信内容使用 `data` ```php 'submail' => [ 'app_id' => '', 'app_key' => '', 'project' => '', // 默认 project，可在发送时 data 中指定 ], ``` ### [螺丝帽](https://luosimao.com/) 短信内容使用 `content` ```php 'luosimao' => [ 'api_key' => '', ], ``` ### [容联云通讯](http://www.yuntongxun.com) 短信内容使用 `template` + `data` ```php 'yuntongxun' => [ 'app_id' => '', 'account_sid' => '', 'account_token' => '', 'is_sub_account' => false, ], ``` ### [互亿无线](http://www.ihuyi.com) 短信内容使用 `content` ```php 'huyi' => [ 'api_id' => '', 'api_key' => '', 'signature' => '', ], ``` ### [聚合数据](https://www.juhe.cn) 短信内容使用 `template` + `data` ```php 'juhe' => [ 'app_key' => '', ], ``` ### [SendCloud](http://www.sendcloud.net/) 短信内容使用 `template` + `data` ```php 'sendcloud' => [ 'sms_user' => '', 'sms_key' => '', 'timestamp' => false, // 是否启用时间戳 ], ``` ### [百度云](https://cloud.baidu.com/) 短信内容使用 `template` + `data` ```php 'baidu' => [ 'ak' => '', 'sk' => '', 'invoke_id' => '', 'domain' => '', ], ``` ### [华信短信平台](http://www.ipyy.com/) 短信内容使用 `content` ```php 'huaxin' => [ 'user_id' => '', 'password' => '', 'account' => '', 'ip' => '', 'ext_no' => '', ], ``` ### [253云通讯（创蓝）](https://www.253.com/) 短信内容使用 `content` ```php 'chuanglan' => [ 'account' => '', 'password' => '', // 国际短信时必填 'intel_account' => '', 'intel_password' => '', // \Overtrue\EasySms\Gateways\ChuanglanGateway::CHANNEL_VALIDATE_CODE => 验证码通道（默认） // \Overtrue\EasySms\Gateways\ChuanglanGateway::CHANNEL_PROMOTION_CODE => 会员营销通道 'channel' => \Overtrue\EasySms\Gateways\ChuanglanGateway::CHANNEL_VALIDATE_CODE, // 会员营销通道 特定参数。创蓝规定：api提交营销短信的时候，需要自己加短信的签名及退订信息 'sign' => '【通讯云】', 'unsubscribe' => '回TD退订', ], ``` ### [创蓝云智](https://www.chuanglan.com/) 普通短信发送内容使用 `content` ```php 'chuanglanv1' => [ 'account' => '', 'password' => '', 'needstatus' => false, 'channel' => \Overtrue\EasySms\Gateways\Chuanglanv1Gateway::CHANNEL_NORMAL_CODE, ], ``` 发送示例： ```php $easySms->send(18888888888, [ 'content' => xxxxxxx ]); ``` 变量短信发送内容使用 `template` + `data` ```php 'chuanglanv1' => [ 'account' => '', 'password' => '', 'needstatus' => false, 'channel' => \Overtrue\EasySms\Gateways\Chuanglanv1Gateway::CHANNEL_VARIABLE_CODE, ], ``` 发送示例： ```php $easySms->send(18888888888, [ 'template' => xxxxxx, // 模板内容 'data' => 'phone":"15800000000,1234；15300000000,4321', ]); ``` ### [融云](http://www.rongcloud.cn) 短信分为两大类，验证类和通知类短信。 发送验证类短信使用 `template` + `data` ```php 'rongcloud' => [ 'app_key' => '', 'app_secret' => '', ] ``` ### [天毅无线](http://www.85hu.com/) 短信内容使用 `content` ```php 'tianyiwuxian' => [ 'username' => '', //用户名 'password' => '', //密码 'gwid' => '', //网关ID ] ``` ### [twilio](https://www.twilio.com) 短信使用 `content` 发送对象需要 使用`+`添加区号 ```php 'twilio' => [ 'account_sid' => '', // sid 'from' => '', // 发送的号码 可以在控制台购买 'token' => '', // apitoken ], ``` ### [tiniyo](https://www.tiniyo.com) 短信使用 `content` 发送对象需要 使用`+`添加区号 ```php 'tiniyo' => [ 'account_sid' => '', // auth_id from https://tiniyo.com 'from' => '', // 发送的号码 可以在控制台购买 'token' => '', // auth_secret from https://tiniyo.com ], ``` ### [腾讯云 SMS](https://cloud.tencent.com/product/sms) 短信内容使用 `template` + `data` ```php 'qcloud' => [ 'sdk_app_id' => '', // 短信应用的 SDK APP ID 'secret_id' => '', // SECRET ID 'secret_key' => '', // SECRET KEY 'sign_name' => '腾讯CoDesign', // 短信签名 ], ``` 发送示例： ```php $easySms->send(18888888888, [ 'template' => 101234, // 模板ID 'data' => [ "a", 'b', 'c', 'd', //按占位顺序给值 ], ]); ``` ### [华为云 SMS](https://www.huaweicloud.com/product/msgsms.html) 短信内容使用 `template` + `data` ```php 'huawei' => [ 'endpoint' => '', // APP接入地址 'app_key' => '', // APP KEY 'app_secret' => '', // APP SECRET 'from' => [ 'default' => '1069012345', // 默认使用签名通道号 'custom' => 'csms12345', // 其他签名通道号 可以在 data 中定义 from 来指定 'abc' => 'csms67890', // 其他签名通道号 ... ], 'callback' => '' // 短信状态回调地址 ], ``` 使用默认签名通道 `default` ```php $easySms->send(13188888888, [ 'template' => 'SMS_001', 'data' => [ 6379 ], ]); ``` 使用指定签名通道 ```php $easySms-