Symfony Notifier Sipgate 桥接：DSN 配置、ssl 选项与底层实现解析

导读

本文围绕 Symfony 开源仓库中 Sipgate Notifier 桥接 的演进记录展开，系统讲解如何通过 Symfony Notifier 接入德国 Sipgate 平台的短信（SMS）发送能力：从 DSN 的完整配置、三个核心参数的含义，到 8.2 版本新增的 ssl DSN 选项（它决定请求走 HTTPS 还是明文 HTTP），再到桥接底层 SipgateTransport 的请求构造、HTTP 认证与错误码处理。读完本文，你将掌握 Sipgate 桥接的完整配置方法、ssl 选项的作用机制，以及如何借助源码与测试验证其行为。

Sipgate 桥接的版本演进

根据 CHANGELOG.md 的记录，该桥接的发展历程非常清晰：

• 7.2：新增 Sipgate 桥接（Add the bridge），即桥接组件首次引入 Symfony Notifier。
• 8.2：新增 ssl DSN 选项，用于让请求通过明文 HTTP 发送（Add the ssl DSN option to send requests over plain HTTP）。

也就是说，默认情况下桥接始终通过 HTTPS 与 Sipgate API 通信；ssl 选项是 8.2 引入的一个"逃生舱"式开关，允许运维人员在受控的测试环境或内网场景下退回到纯 HTTP。这一设计在源码中有清晰印证。

DSN 配置：三个核心参数

桥接包自带的 README.md 给出了标准 DSN 示例：

SIPGATE_DSN=sipgate://TOKEN_ID:TOKEN@default?senderId=SENDER_ID

其中各组成部分的含义为：

DSN 片段	对应参数	说明
TOKEN_ID	Sipgate API Token ID	用于 HTTP Basic 认证的用户名部分
TOKEN	Sipgate API Token	用于 HTTP Basic 认证的密码部分
SENDER_ID	Sipgate 设备 ID	短信发送方设备标识，例如 s1
default	主机占位符	会被解析为默认 API 主机 api.sipgate.com
ssl（可选）	布尔选项	8.2 起可用，ssl=0 时退化为明文 HTTP

将 DSN 写入环境变量 SIPGATE_DSN 后，Symfony Notifier 会自动识别 sipgate:// scheme 并交由 Sipgate 桥接处理。也可以从命令行临时发送短信验证配置，Notifier 组件的 notifier:push / notifier:email 之外，短信类消息经 texter 服务发送，Sipgate 桥接即作为 texter transport 之一被解析。

ssl 选项：让请求走明文 HTTP

这是 8.2 版本的核心变更。要理解它，需要看桥接工厂与基类的协作链条。

工厂侧：解析 ssl 选项

SipgateTransportFactory.php 在创建传输对象时，会依次从 DSN 中取出 Token ID、Token、必填的 senderId，最后调用 $this->getSsl($dsn) 并把结果传给传输对象：

$tokenId = $this->getUser($dsn);
$token = $this->getPassword($dsn);
$senderId = $dsn->getRequiredOption('senderId');
$host = 'default' === $dsn->getHost() ? null : $dsn->getHost();
$port = $dsn->getPort();

return (new SipgateTransport($tokenId, $token, $senderId, $this->client, $this->dispatcher))
    ->setHost($host)->setPort($port)->setSsl($this->getSsl($dsn));

getSsl() 定义在 Notifier 组件的 AbstractTransportFactory.php 中：

protected function getSsl(Dsn $dsn): ?bool
{
    return null === $dsn->getOption('ssl') ? null : $dsn->getBooleanOption('ssl');
}

可见 ssl 是一个可选布尔 DSN 选项：不写该选项时返回 null（跟随默认值，即 HTTPS）；显式写 ssl=0 时返回 false，请求退化为明文 HTTP；写 ssl=1 则强制 HTTPS。

传输侧：决定协议 scheme

SipgateTransport.php 发送短信时构造的端点正是由 getHttpScheme() 决定的：

$endpoint = \sprintf('%s://%s/v2/sessions/sms', $this->getHttpScheme(), $this->getEndpoint());

getHttpScheme() 定义在 AbstractTransport.php：

protected function getHttpScheme(): string
{
    return ($this->ssl ?? static::SSL) ? 'https' : 'http';
}

结合 setSsl(?bool $ssl)（见 AbstractTransport.php），可以推断出完整的协议选择逻辑：

• ssl 选项未设置（null）→ 使用基类常量 static::SSL（默认 true）→ HTTPS；
• ssl=1 → HTTPS；
• ssl=0 → 明文 HTTP。

从源码结构看，ssl=0 的典型适用场景是本地联调、内网代理或需要抓包排查的测试环境；生产环境应保持默认 HTTPS，避免明文传输 Token 与短信内容。

底层发送实现：请求构造与错误处理

SipgateTransport.php 中的 doSend() 是完整的发送链路，值得逐段拆解。

消息类型与端点

桥接只支持短信消息：supports() 仅接受 SmsMessage 实例，doSend() 中对非 SmsMessage 消息抛出 UnsupportedMessageTypeException。发送目标为 Sipgate REST API 的 v2/sessions/sms 端点，主机默认是 api.sipgate.com（见 SipgateTransport.php 的 HOST 常量）。

认证与请求体

请求使用 HTTP Basic 认证，Token ID 与 Token 直接作为 auth_basic 凭据，请求体为 JSON：

$options = [];
$options['smsId'] = $this->senderId;
$options['message'] = $message->getSubject();
$options['recipient'] = $message->getPhone();

$response = $this->client->request('POST', $endpoint, [
    'headers' => [
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
    'auth_basic' => [$this->tokenId, $this->token],
    'body' => json_encode($options),
]);

其中短信内容来自 SmsMessage::getSubject()，接收号码来自 SmsMessage::getPhone()。值得注意的细节是，Token 属性被标注为 #[\SensitiveParameter]，防止在异常堆栈中泄露敏感凭据。

状态码语义

发送结果完全依据 HTTP 状态码判定，从源码可提取出完整的错误码对照表：

状态码	含义	处理结果
204	发送成功	返回 SentMessage
401	认证失败	TransportException：Token ID 或 Token 错误
402	余额不足	TransportException：账户余额不足
403	权限问题	TransportException：无 SMS 权限 / 密码需重置 / senderId 错误
其他	未知错误	TransportException，附带原始状态码

网络层失败（如无法连接服务器）时同样会抛出 TransportException，提示 "Could not reach the remote Sipgate server."。这些语义与测试用例完全对应（见下文）。

测试验证：行为与文档一致

桥接的测试同时覆盖了成功与失败两条路径，是验证上述行为的最佳证据。

传输层测试

SipgateTransportTest.php 使用 MockHttpClient 模拟服务端响应：

• testSendSuccessfully：模拟 204 响应，断言返回 SentMessage 实例；
• testExceptionIsThrownWhenSendFailed：通过 errorProvider 依次验证 401、402、403、415 四类错误码抛出的 TransportException 消息，例如 401 对应 "tokenId or token is wrong."，402 对应 "insufficient funds."，403 对应 "no permission to use sms feature or password must be reset or senderId is wrong."，与 SipgateTransport.php 的实现一一对应；
• supportedMessagesProvider / unsupportedMessagesProvider：确认仅 SmsMessage 被支持，ChatMessage 等其他消息类型被拒绝；
• toStringProvider：断言传输对象的字符串表示 sipgate://api.sipgate.com?senderId=s1，印证默认主机与 DSN 参数的解析结果。

工厂层测试

SipgateTransportFactoryTest.php 验证 DSN 解析规则：

• createProvider：确认 sipgate://host.test?senderId=s1 可被正常解析创建；
• supportsProvider：确认只有 sipgate:// scheme 被支持，其他 scheme 返回 false；
• unsupportedSchemeProvider：非 sipgate scheme 或缺少 senderId 的 DSN 均不可用；
• incompleteDsnProvider：缺少 Token ID 或 Token 的 DSN 被视为不完整配置。

安装与接入小结

桥接包以独立的 symfony/sipgate-notifier 发布（见 composer.json，要求 PHP >= 8.4.1、symfony/notifier ^8.2、symfony/http-client ^7.4|^8.0），与 Symfony Notifier 的常规接入方式一致：通过 Composer 安装对应包，在 .env 中设置 SIPGATE_DSN 环境变量，再通过 TexterInterface 发送 SmsMessage 即可。

实践要点回顾：

1. DSN 三要素：Token ID、Token、senderId 缺一不可，其中 senderId 为必填 DSN 选项；
2. 协议选择：默认 HTTPS；仅在确实需要明文 HTTP 的受控环境中显式设置 ssl=0；
3. 错误排查：对照 401/402/403 状态码语义可快速定位认证、余额与权限三类常见问题；
4. 消息类型：桥接专用于短信，ChatMessage 等消息请使用其他对应桥接。

如需深入调试，建议阅读 SipgateTransport.php、SipgateTransportFactory.php 及其 Tests 目录，源码与测试共同构成了该桥接最权威的行为说明书。