# tp8-sms

**Repository Path**: sdmingma/tp8-sms

## Basic Information

- **Project Name**: tp8-sms
- **Description**: 发送短信验证码sdk
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-01
- **Last Updated**: 2026-02-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ThinkPHP 短信 SDK (tp8-sms)

一个极简、高性能且深度适配 ThinkPHP 的短信验证码 SDK。支持阿里云、腾讯云等多平台，针对高版本 PHP 及国内开发环境进行了深度优化。

## ✨ 特性

- **多平台支持**：预置阿里云、腾讯云驱动，支持自定义扩展。
- **全版本兼容**：兼容 **PHP 7.4 - PHP 8.5** 以及 **ThinkPHP 6.0 / 8.0+**。
- **极致轻量**：核心包不捆绑任何云厂商 SDK，按需安装，秒级部署。
- **原生直连**：腾讯云驱动采用原生 cURL + 手动签名实现，彻底解决本地开发环境 Guzzle 代理劫持导致的 `Connection refused` 报错。
- **现代 PHP 支持**：完美适配 PHP 8.5，解决了 `setAccessible` 和 `curl_close` 等废弃警告。
- **配置原生**：完美集成 ThinkPHP 服务容器与助手函数。

## 📦 安装

通过 Composer 安装核心包：

```bash
composer require sdmingma/tp8-sms
```

### 按需安装驱动

根据您使用的平台，安装对应的官方 SDK：

- **阿里云**：`composer require alibabacloud/dysmsapi-20170525`
- **腾讯云**：*已内置原生 cURL 实现，无需安装官方 SDK 即可使用，更加轻量！*

## ⚙️ 配置

### 1. 发布配置文件

在项目根目录下执行：

```bash
php think vendor:publish
```

这将在 `config` 目录下生成 `sms.php` 配置文件。

### 2. 配置环境变量 (.env)

为了确保最佳兼容性，请使用**大写下划线**格式配置。

> **⚠️ 重要提示**：由于 ThinkPHP 的 `.env` 解析限制，请务必将短信配置放在 `[WECHAT]` 等其他分组标签**之前**，且注释中**不要包含括号** `()`。

```ini
# --- 短信配置 - 全局配置 ---
SMS_DRIVER=tencent

# 腾讯云配置
SMS_TENCENT_SECRET_ID=您的SecretId
SMS_TENCENT_SECRET_KEY=您的SecretKey
SMS_TENCENT_SDK_APP_ID=您的SdkAppId
SMS_TENCENT_SIGN_NAME=您的短信签名
SMS_TENCENT_CODE_TEMPLATE=您的模板ID

# 阿里云配置
# SMS_ALIYUN_ACCESS_KEY_ID=
# SMS_ALIYUN_ACCESS_KEY_SECRET=
# SMS_ALIYUN_SIGN_NAME=
# SMS_ALIYUN_CODE_TEMPLATE=
```

## 🚀 使用方法

### 基础调用

使用助手函数 `sms()` 快速发送验证码：

```php
// 发送验证码（使用默认驱动）
$result = sms()->sendCode('13800138000', '123456');

if ($result['success']) {
    // 发送成功，返回流水号：$result['data']['serial_no']
}
```

### 切换驱动

```php
// 临时切换到阿里云发送
sms()->driver('aliyun')->sendCode('13800138000', '123456');
```

### 发送通知短信

```php
// 腾讯云 - 模板参数使用索引数组
sms()->send('13800138000', '模板ID', ['参数1', '参数2']);

// 阿里云 - 模板参数使用关联数组
sms()->send('13800138000', '模板ID', ['code' => '1234', 'name' => '张三']);
```

## 🛠 错误处理

SDK 会在遇到错误时抛出 `ThinkSms\Exceptions\SmsException`。

```php
use ThinkSms\Exceptions\SmsException;

try {
    sms()->sendCode('13800138000', '123456');
} catch (SmsException $e) {
    // 错误信息
    echo $e->getMessage();
    // 详细错误数据（如平台返回的错误码）
    print_r($e->getData());
}
```

## 🔄 扩展驱动

您可以轻松添加自己的驱动（如华为云、七牛云等）：

1. 创建驱动类继承 `ThinkSms\Contracts\AbstractDriver`。
2. 实现 `send()` 和 `sendCode()` 方法。
3. 在应用初始化处调用 `sms()->extend('custom', \app\sms\MyDriver::class)`。

## 开源协议

MIT License