从 CHANGELOG 读懂 Symfony Notifier Mailjet 桥接器：SMS 集成、DSN 配置与版本演进

导读

Mailjet 是广受欢迎的邮件与短信服务提供商，而本仓库的 src/Symfony/Component/Notifier/Bridge/Mailjet 目录实现了 Mailjet SMS 与 Symfony Notifier 组件的官方桥接（bridge）。本文以该桥接的 CHANGELOG.md 为骨架，结合桥接器源码、工厂解析逻辑与单元测试，完整讲解如何通过一条 DSN 接入 Mailjet 发送短信、From 字段的优先级行为、ssl DSN 选项的用法，以及该桥接从 5.4 到 8.2 的能力演进。读完本文，你将能独立完成 Mailjet SMS 通道的安装、配置、发送与排错。

一、桥接器是什么：Mailjet × Symfony Notifier

Symfony Notifier（Symfony\Component\Notifier）是 Symfony 的统一通知组件，它通过“传输层（Transport）”屏蔽不同服务商（Twilio、Mailjet、Vonage 等）的 API 差异，开发者只需用统一的 SmsMessage / ChatMessage 构造消息即可发送。

Mailjet 桥接器正是把 Mailjet 的短信发送 API（POST /v4/sms-send）封装成 Symfony Notifier 的一个 Transport。仓库中的目录结构清晰展示了这一职责划分：

• MailjetTransport.php：负责实际发送 HTTP 请求的传输类；
• MailjetTransportFactory.php：负责把 DSN 字符串解析为传输实例；
• README.md：官方使用说明；
• Tests/MailjetTransportTest.php 与 Tests/MailjetTransportFactoryTest.php：行为契约测试。

从 CHANGELOG 看，该桥接经历了三个里程碑：5.4 首次引入（“Add the bridge”）、6.2 支持消息级 From（“Use SmsMessage->from when defined”）、8.2 新增 ssl DSN 选项（“Add the ssl DSN option to send requests over plain HTTP”）。下文逐一展开。

二、安装与 DSN 配置

2.1 安装桥接器

在安装了 Symfony Notifier 的项目中，通过 Composer 引入本桥接器：

composer require symfony/notifier-mailjet

说明：桥接器的依赖与元信息见 composer.json，其功能依赖 Notifier 组件与 HTTP Client 组件；传输基类在缺少 symfony/http-client 时会抛出 LogicException（见 AbstractTransport.php 的构造函数）。

2.2 DSN 格式与参数说明

官方 README.md 给出的 DSN 模板是：

MAILJET_DSN=mailjet://FROM:AUTH_TOKEN@default

DSN 组成部分	取值	含义
scheme	mailjet	桥接器标识，工厂只接受该 scheme
user（FROM）	字母数字发送方 ID	即短信的 From 字段，如 Mailjet
password（AUTH_TOKEN）	Mailjet SMS Auth Token	鉴权令牌，请求时以 auth_bearer 方式携带
host	default 或自定义域名	default 会被工厂转换为 null，最终使用传输类默认主机 api.mailjet.com
port	可选	覆盖默认端口
query 选项	ssl（8.2+）	是否使用 HTTPS，见下文第四部分

在 .env 文件中配置：

MAILJET_DSN=mailjet://Mailjet:YOUR_AUTH_TOKEN@default

配置好后，Notifier 的 TransportInterface 会自动按 scheme 匹配到 MailjetTransportFactory（工厂的 getSupportedSchemes() 返回 ['mailjet']，见 MailjetTransportFactory.php），随后便可用 Mailjet 发送短信。

2.3 DSN 解析与校验的底层逻辑

工厂的 create(Dsn $dsn) 方法展示了 DSN 各字段如何落到传输对象上：

• $authToken = $this->getPassword($dsn);——取 DSN 密码部分；
• $from = $this->getUser($dsn);——取 DSN 用户名部分；
• $host = 'default' === $dsn->getHost() ? null : $dsn->getHost();——把占位主机 default 归一化为 null，从而回落到默认主机；
• $port = $dsn->getPort();——端口覆盖；
• 最后 ->setSsl($this->getSsl($dsn)) 读取 ssl 选项。

值得注意的校验逻辑位于 AbstractTransportFactory.php：getUser() / getPassword() 在对应字段缺失时抛出 IncompleteDsnException。因此一条缺少密码的 DSN（如 mailjet://authtoken@default）会被判定为不合法。这一行为被 Tests/MailjetTransportFactoryTest.php 的 incompleteDsnProvider 显式断言：

'Invalid "mailjet://authtoken@default" notifier DSN: Password is not set.'

三、发送短信：从消息构造到请求发出

3.1 构造 SMS 消息

Symfony Notifier 统一使用 SmsMessage（见 SmsMessage.php）：

use Symfony\Component\Notifier\Message\SmsMessage;
use Symfony\Component\Notifier\Texter\Texter;

$texter = new Texter($transport); // $transport 由工厂根据 MAILJET_DSN 创建

$message = (new SmsMessage('[phone]', 'Hello from Mailjet!'))
    ->from('Mailjet'); // 可选：消息级发送方

$texter->send($message);

SmsMessage 的构造函数签名为 (phone, subject, from = '', options = null)，其中 phone 不允许为空字符串（否则抛出 InvalidArgumentException），并提供 phone()、subject()、from() 等流式方法。

3.2 传输类的发送流程

MailjetTransport.php 的核心是 doSend()：

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

$response = $this->client->request('POST', $endpoint, [
    'auth_bearer' => $this->authToken,
    'json' => [
        'From' => $message->getFrom() ?: $this->from,
        'To'   => $message->getPhone(),
        'Text' => $message->getSubject(),
    ],
]);

关键细节：

1. 端点为 {scheme}://api.mailjet.com/v4/sms-send，其中 scheme 由 getHttpScheme() 决定（见下文 ssl 部分）；
2. 鉴权：通过 HTTP 客户端选项 auth_bearer 携带 Mailjet SMS Auth Token，而非请求头手动拼写；
3. 请求体：From、To、Text 三个字段分别取自消息的发送方、手机号与正文；
4. 结果判定：仅当状态码为 200 时认为发送成功并返回 SentMessage；网络层异常（TransportExceptionInterface）会包装为 TransportException（“Could not reach the remote Mailjet server.”）；非 200 时从响应 JSON 的 requestError.serviceException.messageId / text 提取错误信息后抛出。

3.3 支持的消息类型

传输类只接受 SmsMessage（supports() 方法判断 instanceof SmsMessage），对其他消息类型（如 ChatMessage）在 doSend() 中抛出 UnsupportedMessageTypeException。这一约束被 Tests/MailjetTransportTest.php 的 supportedMessagesProvider / unsupportedMessagesProvider 覆盖验证。

四、8.2 新特性：ssl DSN 选项

CHANGELOG 8.2 条目是本文最值得展开的更新：

8.2：Add the ssl DSN option to send requests over plain HTTP（新增 ssl DSN 选项，用于通过明文 HTTP 发送请求）

4.1 默认行为：HTTPS

从 AbstractTransport.php 可见，传输基类定义 protected const SSL = true;，而 getHttpScheme() 的实现为：

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

即：默认（未显式设置 ssl 时）走 https，这正是生产环境的默认安全基线。

4.2 如何切换到明文 HTTP

在 DSN 中追加 ssl 布尔选项即可：

MAILJET_DSN=mailjet://Mailjet:AUTH_TOKEN@default?ssl=0

工厂通过 AbstractTransportFactory::getSsl() 读取该选项：

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

当 ssl=0 时，getHttpScheme() 返回 http，最终发送请求的端点为 http://api.mailjet.com/v4/sms-send。

4.3 适用场景与注意事项

• 该选项解决的是测试环境、内网代理或调试场景下的明文 HTTP 需求（如本地抓包验证请求载荷）；
• 生产环境短信涉及手机号等敏感信息，默认 HTTPS 不应被随意关闭；仅在你明确知道传输链路可信（如内部代理已做 TLS 终结）时才建议使用 ssl=0；
• ssl 是布尔选项，除 0 外也可写作 ssl=false；从源码看它必须能被 getBooleanOption() 解析为布尔值。

五、6.2 特性回顾：消息级 From 的优先级

CHANGELOG 6.2 条目：

6.2：Use SmsMessage->from when defined（当 SmsMessage->from 已定义时使用它）

这条更新对应 doSend() 中 'From' => $message->getFrom() ?: $this->from 这行代码，其语义清晰：

1. 若消息对象显式调用了 from('xxx')（或构造函数传入第三个参数），则以消息级 From 为准；
2. 否则回落到 DSN 中配置的全局发送方 FROM（即 mailjet://FROM:AUTH_TOKEN@default 中的用户名部分）。

这带来两级配置能力：全局默认发送方由 DSN 定义，单条短信的发送方可在消息层临时覆盖。结合 SmsMessage.php 的 from() / getFrom() 方法，可确认该字段在消息对象中自带默认空串，因此 ?: 回退逻辑对未设置 From 的旧代码完全兼容。

六、5.4 起源：桥接器首次引入

CHANGELOG 5.4 条目只有一句话：

5.4：Add the bridge（引入该桥接器）

但它标志着 Mailjet SMS 正式进入 Symfony Notifier 的官方生态。从当前源码可以反推其设计骨架自始就包含：MailjetTransport（基于 AbstractTransport，声明 HOST = 'api.mailjet.com'）、MailjetTransportFactory（基于 AbstractTransportFactory，声明唯一 scheme mailjet），以及配套的工厂/传输测试。后续版本（6.2、8.2）都是在 5.4 这一骨架上做增量演进——这也解释了为何 CHANGELOG 中条目越新越少，因为核心链路早已稳定。

七、用测试锁定行为：工厂与传输的契约

桥接器质量由两组测试保证，它们既是排错时的“行为说明书”，也可作为二次开发时的参考基线：

• Tests/MailjetTransportFactoryTest.php 继承 AbstractTransportFactoryTestCase 并组合 IncompleteDsnTestTrait，断言：
  • mailjet://Mailjet:[e-mail] 可被正确创建为传输实例；
  • 只有 mailjet scheme 受支持（somethingElse://... 返回不支持）；
  • 缺少密码的 DSN 抛出带具体文案的 IncompleteDsnException。
• Tests/MailjetTransportTest.php 继承 TransportTestCase，使用 MockHttpClient 断言：
  • 传输的字符串表示形如 mailjet://[e-mail]；
  • SmsMessage 受支持，ChatMessage 等其他类型被拒绝。

运行测试（在仓库根目录、对该桥接器所在的包结构而言）：

phpunit src/Symfony/Component/Notifier/Bridge/Mailjet/Tests

八、版本演进一览

将 CHANGELOG 三条记录与源码相互印证，可得到 Mailjet 桥接器的能力时间线：

版本	变更	源码/测试佐证
5.4	桥接器首次引入	MailjetTransport.php、MailjetTransportFactory.php
6.2	消息级 From 优先于 DSN 全局发送方	doSend() 中 'From' => $message->getFrom() ?: $this->from
8.2	新增 ssl DSN 选项，可走明文 HTTP	AbstractTransportFactory.php 的 getSsl()、AbstractTransport.php 的 getHttpScheme()

九、快速上手速查

1. composer require symfony/notifier-mailjet；
2. .env 写入 MAILJET_DSN=mailjet://Mailjet:AUTH_TOKEN@default；
3. 需要明文 HTTP 时改为 mailjet://Mailjet:AUTH_TOKEN@default?ssl=0（仅限可信链路或调试）；
4. 构造 SmsMessage 并 ->from() 覆盖单条短信发送方（可选）；
5. 发送后仅 200 视为成功，非 200 与网络异常均由 TransportException 携带具体错误信息抛出。

至此，你已完整掌握 Mailjet 桥接器的 DSN 语法、发送链路、ssl 选项与 From 优先级，可据此在真实项目中安全、高效地接入 Mailjet 短信通道。