# thinkplus-sms

**Repository Path**: okcoder/thinkplus-sms

## Basic Information

- **Project Name**: thinkplus-sms
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-13
- **Last Updated**: 2025-11-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ThinkPlus SMS

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

## 功能特性

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

## 安装

使用 Composer 安装：

```bash
composer require okcoder/thinkplus-sms
```

## 配置

### 1. 发布配置文件

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

### 2. 配置短信服务商

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

```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` 文件中配置短信服务商密钥：

```ini
# 阿里云短信配置
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
```

## 数据库迁移

创建短信日志表：

```bash
php think migrate:run
```

或者手动创建表结构：

```sql
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. 发送普通短信

```php
use Okcoder\ThinkplusSms\facade\ThinkPlusSMS;

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

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

### 2. 发送验证码短信

```php
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. 依赖注入方式

```php
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`: 绑定手机验证码

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

## 异常处理

```php
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();
}
```

## 命令行工具

查看短信日志表结构：

```bash
php think sms:table
```

## 支持的网关

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

## 更新日志

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

## 许可证

MIT

## 贡献

欢迎提交 Issue 和 Pull Request！

## 联系作者

- 邮箱: okcoder@foxmail.com
- GitHub: [https://gitee.com/okcoder](https://gitee.com/okcoder)