2020.08.13 升级,版本升级至2.0.1,SDK升级至3.0.232
2020.06.30 升级,版本升级至2.0,采用全新SDK 3.0
2019.09.20 升级,新增对国际/港澳台短信的支持。
2019.08.02 升级,新增对多个签名或模板的支持。
2019.07.21 升级,新增自动生成验证码功能,调用时code设置为0或空即可,具体参见插件目录下README.md文件。
本插件为腾讯验证码短信、通知短信通用版。安装一个插件,可以同时为手机短信验证和其它信息通知、营销推广等使用。2.0版开始使用腾讯云API 3.0标准的SDK, 为以后升级拓展功能做好基础。
另外需要说明的是,腾讯云短信会有诸多的规范,例如群发短信一次不得超过200条,因此使用本插件之前,请熟知相关规范。
为了能够正常使用本插件,在使用之前,你需要开通腾讯云短信,并准备好各项参数。每个参数的获取和注意事项,请仔细查阅腾讯云短信的相关说明。
请确认你已经开通了腾讯云短信服务,如未开通,请参见 国内短信快速入门 。
如需发送国内短信,需要先 购买国内短信套餐包 。
已在 【访问管理控制台】 >【 API密钥管理 】页面获取 SecretID 和 SecretKey。
SecretID 用于标识 API 调用者的身份。
SecretKey 用于加密签名字符串和服务器端验证签名字符串的密钥,SecretKey 需妥善保管,避免泄露
已经创建了应用,正确获取到了SDK AppID和App Key
已经建立,并审核通过了短信模板,相关概念请参阅 常用概念 。
本插件依赖腾讯云SDK 3.0。虽然插件会自动判断并安装该依赖包,但安装路径默认为插件所在文件夹。所以如果你想统一管理依赖,不希望依赖包安装在插件文件夹下, 或者还需要在其它地方用到该SDK,那么请在安装插件之前,提前安装好依赖。
安装方法:
composer require tencentcloud/tencentcloud-sdk-php
特别说明: 由于安装包内文件比较多,有时可能会解压超时导致安装失败,此时请将data文件夹下的安装包手动解压至插件根目录下,即crazy_sms_tencent下,再次安装即可。
将本插件复制到public\plugins
文件夹下。
进入ThinkCMF后台管理,找到并点开【插件中心】->【插件列表】,在右侧找到腾讯云短信插件
,点击“安装”按钮,提示成功表示正确安装。
在上述界面安装成功后,点击“设置”按钮,会弹出设置界面,将相关参数填好保存即可。自v2.0开始,所有设置参数都不是必须的,只是为调用快捷而已。用户在使用插件时, 可以自己组织参数。各项设置说明如下:
SecretId与SecretKey为腾讯云账户密钥对,为全部SDK通用。如果你已经在应用中其它地方设置,而不想重复设置,请在调用插件时务必携带该参数,否则将会报错,具体请参阅使用部分。
App Key在SDK 3.0短信接口中为非必要参数,因此可以不填写。
国家区号置空或者默认为中国,即86,不必填写前缀+
,插件会自动添加。
短信签名在SDK 3.0短信接口中为非必要参数,但仍然推荐填写,因为多数手机会提取该字段做为通知提醒的关键字。
SenderId为国际短信参数,国内短信请置空,而国际短信则必须填写。
由于短信验证码的需求量非常大,因此可以在此设置模板ID,以便减少调用时的参数。但这并不意味着本插件只能发送验证码,其它短信请参阅使用部分。
请求超时时间,默认为置空,即60秒。
短信模板参数是为方便组织参数的,非必选项。因为腾讯短信模板严格要求参数顺序,而你在组织参数时又不希望每次都考虑该顺序,那么可以在此设置参数顺序。 腾讯短信模板的参数顺序是用数字代替的,比如你的模板设置是这样:
{1} 给您留言了,留言时间:{2},联系电话:{3},请及时查阅并回复。
而开发时,传送给插件的参数是这样:
$param = [ 'templateParams' => [ 'time' => '2019/08/18 14:38:52', 'sender' => '留言者姓名', 'mobile' => '13900000000' ], // …… 其它参数];
那么此时按照模板顺序,将对应的参数名(其实就是数组的键名)输入,参数间用英文逗号分开,则该配置项填写sender,time,mobile
,表示这3个参数按顺序对应短信模板中的{1},{2},{3}。在组织模板参数时,只要将相应的参数配置好即可。
如果此处不配置,那么每次在组织参数时,一定要严格遵守模板的参数顺序,示例:
$param = [ 'templateParams' = ['留言者姓名', '2019/08/18 14:38:52', '13900000000'], // …… 其它参数];
在需要使用腾讯云短信的地方,调用ThinkCMF钩子。本插件使用的是系统钩子:send_mobile_verification_code
。例如:
// 组织参数$params = [ 'mobile' => '13900000000', 'templateParams' => [ 'code' => '341098', 'expire' => '5' ]];// 调用钩子并获取返回结果$result = hook_one('send_mobile_verification_code', $params);// 对结果进行判断处理if (empty($result['error'])) { // TODO 验证码发送正确的逻辑}
所有参数的值类型必须为字符串,不支持其它类型
参数类型为数组
所有参数的键值大小写敏感
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
mobile | string/array | 是 | 手机号码,单一手机号可以使用字符串或数组,多个手机号必须使用数组 |
templateParams | string/array | 否 | 模板参数,如果设置中配置了参数序列,则可以使用键值对形式,否则按模板顺序放置元素。 |
templateId | string | 否 | 模板id,如果没有指定,则使用插件设置中的验证码模板id |
smsSign | string | 否 | 短信签名,国内短信必填。必须填写已审核通过的签名,编码为UTF-8 |
nationCode | string | 否 | 国际码,默认为中国(86) |
senderId | string | 否 | 国际/港澳台短信 senderid,国内短信填空 |
sessionContext | string | 否 | 用户的 session 内容,在返回结果中会原样返回,防止调用过程中丢失某些信息时使用 |
secretId | string | 否 | 云账户SecretId,如未指定则使用插件设置中的配置项 |
secretKey | string | 否 | 云账户SecretKey,如未指定则使用插件设置中的配置项 |
appID | string | 否 | 用户指定的SDK AppID,如未指定则使用插件设置中的配置项 |
发送验证码是最常见的操作,下边的示例默认已经在插件设置中,配置好了相关参数。另外,从v2.0开始,不再支持自动生成验证码,因此验证码请提前生成。 ThinkCMF自带验证码生成和校验函数,请参阅ThinkCMF用户手册。
// 获取用户手机号$mobile = '13900000000';// 生成验证码。该函数第2个参数为验证码长度,默认值为6$code = cmf_get_verification_code($mobile, 4);// 组织插件参数$params = [ 'mobile' => $mobile, 'templateParams' => [$code]];// 调用插件并获取结果$result = hook_one('send_mobile_verification_code', $params);// 对结果进行处理if (empty($result['error'])) { // 发送成功,进行处理} else { // 发送失败,$result通常为['error' => 1, 'message' => '错误信息'] }
本示例为完整调用,对于在插件设置中已经配置的参数项,可以根据实际情况省略。为了更好地展示参数结果,所有数据均为写死,请在实际开发过程中自行生成处理。
$params = [ 'mobile' => [ // 多个手机号请使用数组形式 '13900000000', '13800000000' ], 'templateParams' => [ // 此处假设后台已经配置了参数顺序,使用键值对形式,更加直观 'subject' => '主题信息', 'title' => '信息标题', 'msg' => '信息内容', 'time' => '消息时间' ], 'templateId' => '1400000084', // 通常是14开头的 'smsSign' => '惠达浪博客', // 短信签名 'nationCode' => '86', // 国际区号 'senderId' => 'sender', // 国际/港澳台短信 senderid,我也没见过,瞎写一个吧 'sessionContext' => '{lang: "en"}', // 其它内容,防止页面跳转丢失 'secretId' => config('app.secretId'), // 使用系统统一配置的信息 'secretKey' => config('app.secretKey'), 'appID' => config('app.appID')];// 调用插件并获取结果$result = hook_one('send_mobile_verification_code', $params);// 对结果进行处理if (empty($result['error'])) { // 发送成功,进行处理} else { // 发送失败,$result通常为['error' => 1, 'message' => '错误信息'] }
如果没有安装插件,或者插件安装不正确,返回结果为false
。
插件执行正常,返回结果为数组。特别说明:由于插件没有判定腾讯云错误机制(以后可能会添加),因此短信是否真正送成功,还需要判断返回结果中的Code。
// 发生普通错误时返回// error为错误码,message为错误内容['error' => 1, 'message' => '没有提供手机号']// 正确时返回腾讯云对象,插件将其转换成数组,如需要按对象处理,请与作者联系[ 'SendStatusSet' => [ [ 'SerialNo' => '8:PkiKHqqVpVOPQwkvEDZ20200630', 'PhoneNumber' => '+8613900000000', 'Fee' => 1, 'SessionContext' => '', 'Code': 'Ok', 'Message' => 'send success' ], [ // 多个手机号时,其它手机号结果,内容与上边一致 ] ], 'RequestId' => '9a5e3786-4af8-432b-9d98-ec4154a7be7e']
结果说明:
参数 | 类型 | 说明 |
---|---|---|
SendStatusSet | array | 发送结果状态集,二维数组,包括每个手机号发送的结果 |
RequestId | string | 本次请求的id |
结果集说明:
参数 | 类型 | 说明 |
---|---|---|
SerialNo | string | 系列号,表示每个手机的发送序列 |
PhoneNumber | string | e.164 标准的手机号码 |
Fee | int | 本次发送消耗的短信数指标,过长的短信会被拆分,因此可能会大于1 |
Code | string | 返回状态码,成功为OK,失败时为腾讯SDK错误码 |
Message | string | 状态信息,成功时为send success,失败时为对应的错误消息 |
如果需要错误码的详细信息,请参阅腾讯云API文档 |
2.0.1
2020.08.13
- 升级腾讯SDK包为Tencent Cloud SDK 3.0.2322020.06.30
升级腾讯SDK包为Tencent Cloud SDK 3.0.199
更新系统设置方式和提示信息内容
全新的使用方式,更加灵活
2019.09.20
新增对国际电话的支持
2019.08.02
新增对多模板及签名的支持
2019.07.21
新增自动生成短信验证码功能
重构服务层逻辑,优化代码
2019.07.16 正式版发布!
内置腾讯短信官方SDK,不必单独安装。
ThinkCMF模板插件交流群:550851374 ,领取阿里云1000通用代金券