README

基于 ThinkPHP 6.x 的短信发送扩展包，集成 overtrue/easy-sms 库，支持阿里云、腾讯云等主流短信服务商。

功能特性

✅ 支持多种短信服务商（阿里云、腾讯云、云片等）
✅ 短信验证码发送与验证
✅ 短信发送日志记录
✅ 事件驱动的短信模板管理
✅ 多网关故障转移策略
✅ ThinkPHP 6.x 原生支持

安装

使用 Composer 安装：

composer require okcoder/thinkplus-sms

配置

1. 发布配置文件

php think vendor:publish --tag=thinkplus-sms

2. 配置短信服务商

编辑 config/thinkplus-sms.php 文件：

return [
    // HTTP 请求的超时时间（秒）
    'timeout' => 5.0,

    // 默认发送配置
    'default' => [
        // 网关调用策略，默认：顺序调用
        'strategy' => \Overtrue\EasySms\Strategies\OrderStrategy::class,

        // 默认可用的发送网关
        'gateways' => [
            'aliyun',
        ],
    ],

    // 可用的网关配置
    'gateways' => [
        'aliyun' => [
            'access_key_id' => env('ALIYUN_SMS_ACCESS_KEY_ID'),
            'access_key_secret' => env('ALIYUN_SMS_ACCESS_KEY_SECRET'),
            'sign_name' => env('ALIYUN_SMS_SIGN_NAME'),
            'events' => [
                'register' => 'SMS_123456789', // 注册验证码模板
                'login' => 'SMS_987654321',    // 登录验证码模板
            ],
        ],
        'qcloud' => [
            'sdk_app_id' => env('QCLOUD_SMS_SDK_APP_ID'),
            'secret_id' => env('QCLOUD_SMS_SECRET_ID'),
            'secret_key' => env('QCLOUD_SMS_SECRET_KEY'),
            'sign_name' => env('QCLOUD_SMS_SIGN_NAME'),
            'events' => [
                'register' => '123456',
            ],
        ],
    ],
    
    // 数据库配置
    'database' => [
        'table' => 'sms_logs'
    ],
    
    // 验证码配置
    'captcha' => [
        'cache_prefix' => 'sms_captcha:',
        'length' => 6,      // 验证码长度
        'codeKey' => 'code', // 验证码参数名
        'expire' => 60,     // 验证码过期时间（秒）
    ],
];

3. 环境变量配置

在 .env 文件中配置短信服务商密钥：

# 阿里云短信配置
ALIYUN_SMS_ACCESS_KEY_ID=your_access_key_id
ALIYUN_SMS_ACCESS_KEY_SECRET=your_access_key_secret
ALIYUN_SMS_SIGN_NAME=your_sign_name

# 腾讯云短信配置
QCLOUD_SMS_SDK_APP_ID=your_sdk_app_id
QCLOUD_SMS_SECRET_ID=your_secret_id
QCLOUD_SMS_SECRET_KEY=your_secret_key
QCLOUD_SMS_SIGN_NAME=your_sign_name

数据库迁移

创建短信日志表：

php think migrate:run

或者手动创建表结构：

CREATE TABLE `sms_logs` (
  `id` int(11) unsigned NOT NULL AUTO_INCREMENT,
  `gateway` varchar(50) DEFAULT NULL COMMENT '网关名称',
  `mobile` varchar(20) DEFAULT NULL COMMENT '手机号',
  `template_code` varchar(100) DEFAULT NULL COMMENT '模板代码',
  `biz_id` varchar(100) DEFAULT NULL COMMENT '业务ID',
  `request_params` json DEFAULT NULL COMMENT '请求参数',
  `request_result` json DEFAULT NULL COMMENT '请求结果',
  `notify_data` json DEFAULT NULL COMMENT '回调数据',
  `status` varchar(20) DEFAULT NULL COMMENT '发送状态',
  `create_time` datetime DEFAULT CURRENT_TIMESTAMP,
  `update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  KEY `idx_mobile` (`mobile`),
  KEY `idx_create_time` (`create_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='短信发送日志';

使用方法

1. 发送普通短信

use Okcoder\ThinkplusSms\facade\ThinkPlusSMS;

// 发送短信
ThinkPlusSMS::send('register', '13800138000', [
    'code' => '123456'
]);

// 指定网关发送
ThinkPlusSMS::send('login', '13800138000', [
    'code' => '654321'
], ['aliyun']);

2. 发送验证码短信

use Okcoder\ThinkplusSms\facade\ThinkPlusSMS;

// 发送验证码
$result = ThinkPlusSMS::sendCaptcha('register', '13800138000');
// 返回: ['sms_captcha_key' => 'xxx', 'sms_captcha_time' => 60]

// 验证验证码
$isValid = ThinkPlusSMS::checkCaptchaCode($result['sms_captcha_key'], '123456');

3. 依赖注入方式

use Okcoder\ThinkplusSms\Client;

class SmsController
{
    protected $smsClient;
    
    public function __construct(Client $smsClient)
    {
        $this->smsClient = $smsClient;
    }
    
    public function sendSms()
    {
        $this->smsClient->send('register', '13800138000', [
            'code' => '123456'
        ]);
    }
}

事件说明

在配置文件中，events 字段用于定义不同业务场景对应的短信模板：

register: 用户注册验证码
login: 用户登录验证码
password_reset: 密码重置验证码
bind_mobile: 绑定手机验证码

你可以根据业务需求添加更多事件类型。

异常处理

use Overtrue\EasySms\Exceptions\NoGatewayAvailableException;

try {
    ThinkPlusSMS::send('register', '13800138000', ['code' => '123456']);
} catch (NoGatewayAvailableException $e) {
    // 所有网关都发送失败
    $results = $e->getResults();
    foreach ($results as $gateway => $result) {
        echo "网关 {$gateway} 发送失败: " . $result['exception']->getMessage();
    }
} catch (\Exception $e) {
    // 其他异常
    echo "发送失败: " . $e->getMessage();
}

命令行工具

查看短信日志表结构：

php think sms:table

支持的网关

阿里云短信 (aliyun)
腾讯云短信 (qcloud)
云片短信 (yunpian)
容联云通讯 (rongcloud)
更多网关请参考 overtrue/easy-sms

更新日志

v1.0.0

初始版本发布
支持阿里云、腾讯云短信服务
集成短信验证码功能
添加短信发送日志记录

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！

联系作者

邮箱: okcoder@foxmail.com
GitHub: https://gitee.com/okcoder

okcoder / thinkplus-sms

Maintainers

Details