ThinkCMF 腾讯云短信插件

最后更新：2024.11.08 版本3.0。

插件下载地址

ThinkCMF5 腾讯云短信插件 ver 3.0

功能简介

本插件为腾讯云短信通用版，支持国内、国际/港澳台短信发送。3.0版更换为腾讯云SDK短信专用版。由于使用了PHP新特性，因此PHP版本最低要求为7.1。

另外需要说明的是，腾讯云短信会有诸多的规范，例如群发短信一次不得超过200条，因此使用本插件之前，请熟知相关规范。

准备

为了能够正常使用本插件，在使用之前，你需要开通腾讯云短信，并准备好各项参数。每个参数的获取和注意事项，请仔细查阅腾讯云短信的相关说明，相关概念请参阅 常用概念。

1. 请确认你已经开通了腾讯云短信服务，如未开通，请参见 腾讯短信文档 。

2. 国内短信，需要先购买短信套餐包，国内短信套餐包购买
   ，国际/港澳台短信目前使用后付费方式，请确保腾讯云账号内有充足的余额。

3. 请在 【访问管理控制台】 >【 API密钥管理 】页面获取 SecretID 和 SecretKey。

• SecretID 用于标识 API 调用者的身份。

• SecretKey 用于加密签名字符串和服务器端验证签名字符串的密钥
  SecretID和SecretKey非常重要，需妥善保管，避免泄露。

• 国内短信需要短信签名，请在短信签名处申请。国际/港澳台短信不强制要求，可有可无。

• 创建短信模板，转至国内短信创建，
  国际/港澳台短信模板请转至国际/港澳台短信，并获取模板ID。

• 国内短信需要创建应用，请创建应用并获取SDK AppID。国际/港澳台短信无此选项。

• 国际/港澳台短信SenderID，可选，请参考国际/港澳台短信 Sender ID 说明

• 国际/港澳台短信还需获知相应国家的电话国际区号。

Tips: 创建模板时请仔细阅读费用说明，超过固定字数短信将被拆分为2条发送，费用也是收取2条。设计模板时要将变量参数考虑进去。

安装

Tips:
本插件依赖腾讯云短信SDK 3.0。虽然插件会自动判断并安装该依赖包，但安装路径默认为插件所在文件夹。所以如果你想统一管理依赖，不希望依赖包安装在插件文件夹下，或者还需要在其它地方用到该SDK，那么请在安装插件之前，提前安装好依赖。

安装方法：

composer require tencentcloud/sms

特别说明： 由于安装包内文件比较多，有时可能会解压超时导致安装失败，此时可将data文件夹下的安装包手动解压至插件根目录下，即crazy_sms_tencent下，再次安装即可。

1. 将本插件复制到public\plugins文件夹下。

2. 进入ThinkCMF后台管理，左侧菜单中找到并点开【应用中心】->【插件管理】，在右侧找到【腾讯云短信插件】，点击 + 按钮，提示成功表示正确安装。
   如果安装失败，及有可能是因为你的ThinkCMF版本为5.0.x，并且没有安装腾讯云SDK，请手动安装。

Tips：
如果是5.1以上版本安装失败，则有可能是插件目录没有写入权限，可以手动解压data\tencentCloudSms.zip至插件目录：
public\plugins\crazy_sms_tencent下，再安装。

设置

在上述界面安装成功后，点击插件列表右侧操作栏中的“设置”按钮，会弹出设置界面，将相关参数填好保存即可。

SecretId与SecretKey为腾讯云账户密钥对，如果按腾讯建议存放于系统环境变量中，则变量名必须为：TENCENTCLOUD_SECRET_ID 和
TENCENTCLOUD_SECRET_KEY。本插件优先从环境变量中读取该参数。

使用

在需要使用腾讯云短信的地方，调用ThinkCMF钩子。本插件使用的是系统钩子：send_mobile_verification_code。例如：

// 基本使用

$params = [
    'phoneNumbers' => ['13900000000'], // 必填，接收短信电话号码，数组。
    'templateParam' => ['341098', '5'] // 选填，如果模板中有变量，请严格按模板设置顺序准备。
];
// 调用钩子并获取返回结果
$result = hook_one('send_mobile_verification_code', $params);
// 对结果进行判断处理
if (empty($result['error'])) {
    // 验证码发送正确的逻辑
}

调用参数的键值说明

所有参数的键值大小写敏感

使用示例

本示例使用所有参数，以国际短信为例展示使用方法。实际开发中，仅在与后台设置不一致时，才会添加相应的参数。例如短信有多个模板，而默认的模板却只能有一个，调用其它模板时需要指定
templateId参数。

{
  "SendStatusSet": [
    {
      "SerialNo": "d09c1bf9-dcce-4f0b-9233-64a631b51cc2",
      "PhoneNumber": "+971543230000",
      "Fee": 2,
      "SessionContext": "",
      "Code": "Ok",
      "Message": "send success",
      "IsoCode": "AE"
    }
  ],
  "RequestId": "0506d2cf-1190-4a23-a260-bab1ee93e6d7"
}

$params = [
  'phoneNumbers'   => ['543891098', '569721146'], // 多个电话号码
  'templateId'     => '1400000084', // 通常是14开头的
  'templateParams' => ['参数一', '参数二', '参数三'], // 多个模板参数
  'signName'       => '某公司通知短信', // 短信签名
  'nationCode'     => '971', // 国际区号
  'senderId'       => 'Company Name', // 国际/港澳台短信 senderid，我也没见过，瞎写一个吧
  'secretId'       => getenv('TENCENTCLOUD_SECRET_ID'), // 从环境变量中获取
  'secretKey'      => config('app.secretKey'), // 从应用配置中获取
  'appID'          => '1400787878', // 其它方式指定
  'sessionContext' => '{lang: "en"}', // 需要保留的session内容，防止页面跳转丢失
  'region'         => 'ap-guangzhou' // 指定广州服务器
];

// 调用插件并获取结果
$result = hook_one('send_mobile_verification_code', $params);
// 对结果进行处理
if (empty($result['error'])) {
  // 发送成功，进行处理
} else {
  // 发送失败，$result通常为['error' => 1, 'message' => '错误信息'] 
}

返回结果说明

• 如果没有安装插件，或者插件安装不正确，返回结果为false。

• 插件执行正常，返回结果为数组。数组键值包含error与message。如果error值为 0 表示正常，为 1 表示错误。message包含信息。

Tips: 成功发送请求后，返回结果error的值为 0，但并不能表示短信发送成功！还需要对返回结果进行处理。因为返回结果包含很多信息，因此作者不能简化处理，而是将结果的json字符串原样输出到
message中，开发人员需要自行处理。例如判断结果中的Code字段是否为’Ok’。

// 发生普通错误时返回
// error为错误码，message为错误内容
[‘error’ => 1, ‘message’ => ‘没有提供手机号’]

// 成功时返回Json字符串

如果是多个手机号，则SendStatusSet数组中为多个对象。

另外，返回值也用可能是失败信息，如：

{  "SendStatusSet": [    {      "SerialNo": "",      "PhoneNumber": "+8613900000000",      "Fee": 0,      "SessionContext": "",      "Code": "LimitExceeded.PhoneNumberOneHourLimit",      "Message": "the number of sms messages sent from a single mobile number within 1 hour exceeds the upper limit",      "IsoCode": "CN"    }  ],  "RequestId": "6768c8d7-8722-4e60-9d1f-33e077abd9f4"}

结果说明：

结果集说明：

如果需要错误码的详细信息，请参阅腾讯云API文档

更新

v3.0

2024.11.08

• 更换SDK包为腾讯云短信专用包，版本3.0.1159，为腾讯云SDK的子集

• 重构代码，使用了PHP新特性，PHP版本最低要求为7.1

• 不再区分验证码短信与通知短信，使用更方便

• 测试了最新的国内、国际短信，更新了返回结果说明

v2.0.1

2020.08.13

• 升级腾讯SDK包为Tencent Cloud SDK 3.0.232

• 修复出错时，返回结果不正确的bug

v2.0

2020.06.30

• 升级腾讯SDK包为Tencent Cloud SDK 3.0.199

• 更新系统设置方式和提示信息内容

• 全新的使用方式，更加灵活

v1.1.2

2019.09.20

• 新增对国际电话的支持

v1.1.1

2019.08.02

• 新增对多模板及签名的支持

v1.1.0

2019.07.21

• 新增自动生成短信验证码功能

• 重构服务层逻辑，优化代码

v1.0.0

2019.07.16 正式版发布！

• 内置腾讯短信官方SDK，不必单独安装。