开发者调用说明

一、插件概述

DzzOffice 短信服务插件基于 overtrue/easy-sms 封装，支持多网关（阿里云、腾讯云、云片等）自动切换、验证码生成、频率限制等核心能力。开发者仅需通过 全局 sms() 函数 发送短信，通过 C::t('#sms#sms_smslog')->verify() 方法 验证验证码，无需关注底层实现细节，适用于登录、注册、密码重置等场景。

二、前置条件

插件安装与配置

已在 DzzOffice 后台成功安装短信服务插件（参考插件安装向导）；

已在「短信服务 - 网关设置」中至少一个短信网关（如阿里云 AccessKey、腾讯云 SecretId 等）及模板（需与网关侧备案模板一致）。

已在「短信服务 - 模板标识设置」中创建模板，获取模板调用标识（tplsign）。

依赖环境

DzzOffice 版本 ≥ 2.02；

PHP 版本 ≥ 7.2.5。

三、核心接口：sms()函数

函数定义

可选参数 `$params` 说明

参数名	类型	默认值	说明
`codelength`	int	6	可选，验证码长度（4-8位，仅适用于验证码类模板）
`expire`	int	15	可选，验证码有效期（单位：分钟，过期后无法验证）
`smsinterval`	int	60	可选，同一手机号发送间隔（单位：秒，避免短时间内重复发送）
`smstimelimit`	int	300	可选，频率限制时间窗口（单位：秒，默认5分钟内）
`smsnumlimit`	int	5	可选，时间窗口内最大发送次数（超过则拒绝发送）
`mobicc`	int	86	可选，国家码（如中国86，需与手机号匹配）
`uid`	int	0	可选，关联用户ID（用于日志追溯，默认当前登录用户ID）
`gateways`	string	""	可选，如果指定网关（如`aliyun`）将只通过该网关进行发送
`mock`	bool	false	可选，模拟发送（仅记录日志不实际调用网关，用于测试环境）

调用示例

示例1：发送登录验证码（默认配置）

示例2：发送注册通知（自定义参数）

四、验证码验证接口

发送验证码后，通过插件封装的 C::t('#sms#sms_smslog')->verify() 方法验证用户输入的验证码有效性，无需手动查询数据库。

4.1 方法定义

4.2 关键参数 `$appinfo` 说明

键名	类型	默认值	说明
`expire`	int	5	验证码有效期（单位：分钟，与 `sms` 函数的 `expire` 对应，默认5分钟）
`maxAttempts`	int	5	最大验证失败次数（超过则锁定验证码，默认5次）

4.3 验证码状态说明（方法内置）

状态值（`verify` 字段）	含义	处理逻辑
0	未使用（正常）	可参与验证，正确则改1，错误则减1（记失败次数）
1	已验证	重复验证返回失败
2	已锁定	失败次数达 `maxAttempts` 后触发，无法再验证
3	已过期	超过 `expire` 时间后触发，无法再验证
< 0（如-1、-2）	验证失败次数（负数）	绝对值达 `maxAttempts` 后，自动改2（锁定）

4.4 调用示例（验证登录验证码）

五、注意事项

参数一致性：sms 函数的 expire 必须与 verify 方法 appinfo['expire'] 一致，否则会导致“提前过期”或“过期未锁定”；

锁定逻辑：验证码锁定后（状态2），需重新调用 sms 函数获取新验证码，旧验证码无法再使用；

日志排查：发送/验证错误可通过插件「短信服务-短信记录」查看，自动记录每条短信的关键信息，便于定位问题。

一、插件概述#

二、前置条件#

三、核心接口：sms()函数#

函数定义#

可选参数 $params 说明#

调用示例#

示例1：发送登录验证码（默认配置）#

示例2：发送注册通知（自定义参数）#

四、验证码验证接口#

4.1 方法定义#

4.2 关键参数 $appinfo 说明#

4.3 验证码状态说明（方法内置）#

4.4 调用示例（验证登录验证码）#

五、注意事项#