Swift Mailer 已被 Symfony Mailer 取代，自2021年底起终止维护；迁移需更新类名、Transport 配置（显式指定加密）、DSN 编码、模板上下文传递及安装 symfony/http-client 等依赖。
Swift Mailer 已被 Symfony Mailer 取代，PHP 项目应停用
Swift Mailer 自 2021 年底起正式进入维护终止状态（EOL），不再接收安全更新或功能补丁。Symfony 官方明确要求所有新项目使用 Symfony\Mailer，旧项目也应尽快迁移——这不是“可选升级”，而是安全与兼容性刚需。
替换 Swift Mailer 时最常遇到的类名和方法映射
直接替换类名和调用方式会导致报错，比如 Swift_SmtpTransport、Swift_Message、$mailer->send() 全部失效。核心映射关系如下：
-
Swift_SmtpTransport→Symfony\Component\Mailer\Transport\Smtp\EsmtpTransport（注意：需传入SmtpOptions实例，不能直接传 host/port） -
Swift_Message→Symfony\Component\Mailer\Mime\Email（链式调用更严格，text()和html()必须显式指定） -
$mailer->send($message)→$mailer->send($email)（$mailer是Symfony\Component\Mailer\MailerInterface实例） - 附件添加从
$message->attach()改为$email->attach(fopen(...), 'filename.pdf', 'application/pdf')
配置 Transport 时容易漏掉的依赖和参数细节
Mailer 不再自动推断加密方式或认证机制，常见错误如 “Connection could not be established with host smtp.gmail.com” 往往源于 Transport 配置缺失。关键点：
- Gmail SMTP 必须显式启用 TLS：
new SmtpOptions(['host' => 'smtp.gmail.com', 'port' => 587, 'encryption' => 'tls'])；用 465 端口则必须设'encryption' => 'ssl' - 若用环境变量注入配置（如
MAILER_DSN=smtp://user:pass@smtp.gmail.com:587），确保密码已 URL 编码（特殊字符如+、/会破坏 DSN 解析） - 需要安装额外组件：
composer require symfony/mailer symfony/http-client（后者用于 API-based transport 如 Mailgun、SendGrid） - 本地开发建议用
sendmail或logtransport 避免发信失败干扰调试：MAILER_DSN=sendmail://default或log://
模板邮件 + Twig 渲染的写法变化
原来用 Swift_Plugins_TemplatingPlugin 的项目，现在要改用 Symfony\Component\Mailer\Mime\TemplatedEmail，且必须配合 Twig 错误处理逻辑：
立即学习“PHP免费学习笔记（深入）”；
-
TemplatedEmail的htmlTemplate()和textTemplate()接收的是 Twig 模板路径（如'emails/welcome.html.twig'），不是渲染后的 HTML 字符串 - 模板中不能直接访问
$message对象，需通过context()显式传参：$email->context(['user' => $user, 'url' => $url]) - Twig 环境必须已注册到容器（Symfony 项目默认已配），纯 PHP 项目需手动绑定：
$email->embed(new \Symfony\Component\Mailer\Mime\Part\DataPart($imageData, 'logo.png'))才能在模板里用{{ email.image('logo.png') }}
迁移不是简单替换类名，真正卡点往往在 Transport 加密协商、DSN 编码、以及模板上下文传递这三个环节。没报错但收不到邮件？先检查 MAILER_DSN 是否被 shell 截断，再确认 symfony/http-client 是否装全——少一个依赖，sendgrid+api transport 就静默降级成 null transport。
