Symfony LightSms Notifier 桥接：DSN 配置、签名机制与版本演进深度解析

• 后端
• Web框架

本篇指南围绕 Symfony Notifier 组件中 LightSms 桥接的版本演进（CHANGELOG）展开，结合当前仓库源码，系统讲解如何通过lightsms://DSN 接入 LightSms 短信服务、SmsMessage::from发件人优先级规则、以及 8.2 新增的sslDSN 选项，并深入剖析签名生成、手机号转义与错误码映射等底层实现。读完本文，你将能在 Symfony 应用中独立配置并验证一个可用的 LightSms 短信通道。

桥接定位与版本脉络

LightSms 桥接位于 src/Symfony/Component/Notifier/Bridge/LightSms，是 Symfony Notifier 为 LightSms（负责消息发送与响应解析）和 LightSmsTransportFactory.php（负责将 DSN 解析为传输实例）。

该桥接的 CHANGELOG 记录了三个关键里程碑，恰好勾勒出其能力演进的主线：

下面将逐项还原这些变更背后的实现细节。

安装与 DSN 配置

桥接包名为symfony/light-sms-notifier（见 composer.json），要求 PHP>=8.4.1，并依赖symfony/http-client（^7.4|^8.0）与symfony/notifier（^8.2）。可通过 Composer 安装：

composer require symfony/light-sms-notifier

DSN 格式

根据 README.md，DSN 的标准格式为：

LIGHTSMS_DSN=lightsms://LOGIN:TOKEN@default?from=PHONE

其中：

• LOGIN—— 你的 LightSms 登录名；
• TOKEN—— 账户内显示的 Token（在工厂解析中对应 DSN 密码段，见下文）；
• PHONE—— 你的 LightSms 发件人手机号码。

账户信息可从 LightSms 官网的 API 管理页面获取。若将主机段固定为default，工厂会回退到传输类中定义的默认主机；LightSmsTransport.php 声明了protected const HOST = 'www.lightsms.com'，即实际请求目标。

8.2 新增的 ssl 选项

在 8.2 之前，传输默认走 HTTPS；AbstractTransport.php 中定义protected const SSL = true，而getHttpScheme()按($this->ssl ?? static::SSL) ? 'https' : 'http'决定协议。

8.2 的变更让ssl成为可配置的 DSN 选项，从而允许在需要纯 HTTP 的环境下发送请求：

LIGHTSMS_DSN=lightsms://LOGIN:TOKEN@default?from=PHONE&ssl=0

解析逻辑在 AbstractTransportFactory.php 的getSsl()方法中：null === $dsn->getOption('ssl') ? null : $dsn->getBooleanOption('ssl')。随后 LightSmsTransportFactory.php 将结果通过->setSsl($this->getSsl($dsn))注入传输实例：

• ssl=0→ 强制使用http://发送请求；
• 省略ssl→ 回退到类常量SSL（默认true，即 HTTPS）；
• ssl=1→ 显式 HTTPS。

注意：明文 HTTP 会暴露请求参数（含登录名与签名），仅应在受控的测试或内网环境中使用。

6.2 变更：按消息动态指定发件人

6.2 之前，发件人只能来自 DSN 中的from参数；6.2 起，如果SmsMessage实例显式设置了发件人，则优先采用该值。实现位于 LightSmsTransport.php 的doSend()中：

'sender' => $message->getFrom() ?: $this->from,

即sender字段取值遵循：SmsMessage的from（若非空） > DSN 的from参数。

这得益于 SmsMessage.php 的构造签名：__construct(string $phone, string $subject, string $from = '', ...)，其中from默认为空字符串。于是业务代码可以这样按需指定发件人：

use Symfony\Component\Notifier\Notifier; use Symfony\Component\Notifier\Message\SmsMessage; $message = new SmsMessage( phone: '+8613800138000', subject: '您的验证码是 123456', from: '01012345678', // 覆盖 DSN 中的默认发件人 ); $notifier->send($message);

未设置from时（保持空串），?:运算会优雅回退到 DSN 配置的默认发件人，兼容旧版行为。

发送流程与签名机制（源码级）

doSend()的完整流程如下：

1. 类型校验：supports()仅接受SmsMessage，其他消息类型（如ChatMessage）会抛出UnsupportedMessageTypeException；
2. 组装参数：依次收集login、phone、sender、text、timestamp（当前 Unix 时间戳）；
3. 生成签名：generateSignature()先将参数按 key 排序（ksort），再拼接为字符串并追加密码，最后取md5：

   ksort($data); return md5(implode('', array_values($data)).$this->password);

4. 发起 GET 请求：目标为{scheme}://www.lightsms.com/external/get/send.php，参数经query传递；
5. 校验响应：网络异常抛TransportException，非 200 状态码直接失败；
6. 解析业务错误码：从响应数组中提取error字段，非 0 即按错误码表翻译成可读信息（见下节）；
7. 返回 SentMessage：成功时若响应包含id_sms，会写入SentMessage的 message id，供后续状态查询使用。

手机号转义

发送前，escapePhoneNumber()将+前缀统一替换为国际拨号前缀00：

return str_replace('+', '00', $phoneNumber);

例如+37061234567会转换为0037061234567后再发送。

错误码映射表

LightSmsTransport.php 内置了ERROR_CODES常量表，覆盖 1～39 及 999 共数十种业务错误，常见如：

发送失败时，TransportException的消息会携带Unable to send the SMS: {错误描述}，便于快速定位是签名、发件人还是余额问题。

测试验证：DSN 解析与消息支持

仓库中的测试用例直接印证了上述行为：

• LightSmsTransportFactoryTest.php 验证 DSN 解析：lightsms://login:token@host.test?from=0611223344可成功创建传输；缺少用户或密码的 DSN 会被判定为IncompleteDsn（如lightsms://login@default?from=...），而somethingElse://等非lightsmsscheme 则被拒绝；
• LightSmsTransportTest.php 验证消息支持范围：SmsMessage受支持，ChatMessage与其他 dummy 消息均不受支持；__toString()输出形如lightsms://www.lightsms.com?from=from的规范化 DSN。

日常接入后，可运行桥接自带测试确认环境：

cd src/Symfony/Component/Notifier/Bridge/LightSms phpunit

小结

LightSms 桥接虽小，却完整展现了 Symfony Notifier 的桥接范式：Transport承载协议细节，TransportFactory负责 DSN 解析，AbstractTransport提供host/port/ssl基础设施。从 5.3 的首次引入，到 6.2 的按消息指定发件人，再到 8.2 的ssl选项，每一次版本演进都可以在 CHANGELOG.md 与源码一一对应。配置时只需记住三点：DSN 中login/token与from必填，业务发件人可通过SmsMessage覆盖，非 TLS 环境显式追加ssl=0即可。

• 后端
• Web框架