本教程详细介绍了如何在 symfony 5 应用程序中同时实现同步和异步邮件发送。通过利用 symfony messenger 组件的强大功能，我们将学习如何定义自定义消息类和处理器，精确控制邮件的发送方式，从而优化用户体验和系统性能，避免邮件发送阻塞主线程。
在现代 Web 应用中，邮件发送是常见需求。根据场景不同，有时需要即时发送（同步），有时则允许后台处理（异步），以避免阻塞用户界面或长时间运行的任务。Symfony 框架通过其 Mailer 和 Messenger 组件提供了强大的邮件发送能力，但要同时实现同步和异步发送，需要对 Messenger 的工作原理有清晰的理解。
本文将指导您如何在 Symfony 5 应用中优雅地实现这一目标，确保您能根据业务需求灵活选择邮件发送模式。
理解挑战
在 Symfony 中，默认情况下，当您使用 MailerInterface::send() 方法时，邮件是同步发送的。为了实现异步发送，通常会结合 Symfony Messenger 使用。Symfony 提供了一个内置的 Symfony\Component\Mailer\Messenger\SendEmailMessage 消息类，用于将 TemplatedEmail 对象包装成一个 Messenger 消息。
如果您直接在 Messenger 配置中路由这个内置消息：
# config/packages/messenger.yaml
framework:
messenger:
transports:
async: '%env(MESSENGER_TRANSPORT_DSN)%'
routing:
'Symfony\Component\Mailer\Messenger\SendEmailMessage': async这会导致所有通过 MailerInterface::send() 发送的邮件都被 Messenger 捕获并推送到 async 队列，因为 MailerInterface 内部会检查是否存在 Messenger 且 SendEmailMessage 是否被路由。这使得无法同时发送同步邮件。
为了实现灵活的同步/异步发送，我们需要一种机制来明确区分哪些邮件应该异步发送，哪些应该同步发送。解决方案是为异步邮件创建自定义消息和处理器。
步骤一：定义异步邮件消息
首先，我们需要创建一个自定义消息类，它将封装所有发送异步邮件所需的数据。这个消息类应该是一个简单的 PHP 对象，包含邮件的主题、正文模板、收件人、上下文等信息。
src/Message/EmailAsync.php
<?php
namespace App\Message;
class EmailAsync
{
private string $subject;
private string $bodyHtmlTemplate;
private ?string $bodyTextTemplate;
private string $recipient;
private array $context;
private string $senderEmail; // 可选，如果发件人可能不同
public function __construct(
string $subject,
string $bodyHtmlTemplate,
?string $bodyTextTemplate,
string $recipient,
array $context = [],
string $senderEmail = 'no-reply@yourdomain.com' // 默认发件人
) {
$this->subject = $subject;
$this->bodyHtmlTemplate = $bodyHtmlTemplate;
$this->bodyTextTemplate = $bodyTextTemplate;
$this->recipient = $recipient;
$this->context = $context;
$this->senderEmail = $senderEmail;
}
// 为所有属性生成公共的 getter 方法
public function getSubject(): string
{
return $this->subject;
}
public function getBodyHtmlTemplate(): string
{
return $this->bodyHtmlTemplate;
}
public function getBodyTextTemplate(): ?string
{
return $this->bodyTextTemplate;
}
public function getRecipient(): string
{
return $this->recipient;
}
public function getContext(): array
{
return $this->context;
}
public function getSenderEmail(): string
{
return $this->senderEmail;
}
}这个 EmailAsync 类只是一个数据容器，不包含任何发送逻辑。
步骤二：创建异步邮件处理器
接下来，我们需要为 EmailAsync 消息创建一个处理器。当 Messenger 接收到 EmailAsync 消息时，它会调用这个处理器来执行实际的邮件发送操作。
src/MessageHandler/EmailAsyncHandler.php
<?php
namespace App\MessageHandler;
use App\Message\EmailAsync;
use Symfony\Component\Mime\Address;
use Symfony\Bridge\Twig\Mime\TemplatedEmail;
use Symfony\Component\Mailer\MailerInterface;
use Symfony\Component\Messenger\Handler\MessageHandlerInterface;
class EmailAsyncHandler implements MessageHandlerInterface
{
private MailerInterface $mailer;
public function __construct(MailerInterface $mailer)
{
$this->mailer = $mailer;
}
public function __invoke(EmailAsync $emailMessage)
{
// 从 EmailAsync 消息中提取邮件数据
$subject = $emailMessage->getSubject();
$bodyHtmlTemplate = $emailMessage->getBodyHtmlTemplate();
$bodyTextTemplate = $emailMessage->getBodyTextTemplate();
$recipient = $emailMessage->getRecipient();
$context = $emailMessage->getContext();
$senderEmail = $emailMessage->getSenderEmail();
// 构建 Symfony TemplatedEmail 对象
$emailToSend = (new TemplatedEmail())
->from(new Address($senderEmail)) // 使用消息中提供的发件人
->to(new Address($recipient))
->subject($subject)
->htmlTemplate($bodyHtmlTemplate)
->context($context);
if ($bodyTextTemplate) {
$emailToSend->textTemplate($bodyTextTemplate);
}
// 通过 MailerInterface 发送邮件
$this->mailer->send($emailToSend);
}
}EmailAsyncHandler 实现了 MessageHandlerInterface 接口，并通过 __invoke 方法处理 EmailAsync 消息。在这个方法中，它使用注入的 MailerInterface 来构建并发送 TemplatedEmail。
步骤三：配置 Messenger 路由
现在，我们需要告诉 Symfony Messenger，当它遇到 App\Message\EmailAsync 类型的消息时，应该将其路由到哪个传输层（transport）。
config/packages/messenger.yaml
framework:
messenger:
transports:
# 定义一个异步传输层，例如使用 Doctrine 数据库或 RabbitMQ
# DSN 可以来自环境变量，例如 MESSENGER_TRANSPORT_DSN="doctrine://default?queue_name=async_emails"
async: '%env(MESSENGER_TRANSPORT_DSN)%'
routing:
# 将自定义的 EmailAsync 消息路由到异步传输层
'App\Message\EmailAsync': async
# 重要：确保 Symfony\Component\Mailer\Messenger\SendEmailMessage 没有被路由到异步传输
# 这样直接使用 MailerInterface::send() 就会是同步的
# 如果之前有配置，请移除或确保它不指向异步队列
# 'Symfony\Component\Mailer\Messenger\SendEmailMessage': null # 或者完全不配置此项通过此配置，只有 App\Message\EmailAsync 消息才会被推送到 async 队列。而其他未被路由的消息（包括 Symfony\Component\Mailer\Messenger\SendEmailMessage）将由 Messenger 的默认行为处理，即同步发送（如果没有其他处理器或路由规则）。
步骤四：在服务中发送异步邮件
在您的应用程序服务中，当您需要发送异步邮件时，您将注入 MessageBusInterface 并调度 EmailAsync 消息。
src/Service/MailManagerAsync.php
<?php
namespace App\Service;
use App\Message\EmailAsync;
use Symfony\Component\Messenger\MessageBusInterface;
class MailManagerAsync
{
private MessageBusInterface $bus;
public function __construct(MessageBusInterface $bus)
{
$this->bus = $bus;
}
/**
* 异步发送邮件。
*
* @param string $subject 邮件主题
* @param string $bodyHtmlTemplate HTML 邮件模板路径
* @param string|null $bodyTextTemplate 纯文本邮件模板路径 (可选)
* @param string $to 收件人邮箱地址
* @param array $context 传递给 Twig 模板的变量
* @param string $senderEmail 发件人邮箱地址 (可选，默认为配置值)
*/
public function sendAsyncEmail(
string $subject,
string $bodyHtmlTemplate,
?string $bodyTextTemplate,
string $to,
array $context = [],
string $senderEmail = 'no-reply@yourdomain.com'
): void {
$emailAsync = new EmailAsync(
$subject,
$bodyHtmlTemplate,
$bodyTextTemplate,
$to,
$context,
$senderEmail
);
$this->bus->dispatch($emailAsync);
}
}现在，当您调用 MailManagerAsync::sendAsyncEmail() 方法时，邮件不会立即发送，而是被封装成 EmailAsync 消息，并推送到 Messenger 队列中等待后台处理。
步骤五：发送同步邮件
对于需要同步发送的邮件，您只需直接注入 MailerInterface 并使用其 send() 方法，无需涉及 Messenger。
src/Service/MailManagerSync.php
<?php
namespace App\Service;
use Symfony\Component\Mime\Address;
use Symfony\Bridge\Twig\Mime\TemplatedEmail;
use Symfony\Component\Mailer\MailerInterface;
class MailManagerSync
{
private MailerInterface $mailer;
private string $defaultSenderEmail; // 可以通过构造函数注入或从配置获取
public function __construct(MailerInterface $mailer, string $defaultSenderEmail = 'no-reply@yourdomain.com')
{
$this->mailer = $mailer;
$this->defaultSenderEmail = $defaultSenderEmail;
}
/**
* 同步发送邮件。
*
* @param string $subject 邮件主题
* @param string $bodyHtmlTemplate HTML 邮件模板路径
* @param string|null $bodyTextTemplate 纯文本邮件模板路径 (可选)
* @param string $to 收件人邮箱地址
* @param array $context 传递给 Twig 模板的变量
* @param string|null $senderEmail 发件人邮箱地址 (可选，默认为配置值)
*/
public function sendSyncEmail(
string $subject,
string $bodyHtmlTemplate,
?string $bodyTextTemplate,
string $to,
array $context = [],
?string $senderEmail = null
): void {
$email = (new TemplatedEmail())
->from(new Address($senderEmail ?? $this->defaultSenderEmail))
->to(new Address($to))
->subject($subject)
->htmlTemplate($bodyHtmlTemplate)
->context($context);
if ($bodyTextTemplate) {
$email->textTemplate($bodyTextTemplate);
}
$this->mailer->send($email);
}
}通过这种方式，MailManagerSync 服务会立即发送邮件，而不会进入任何队列。
总结与注意事项
通过上述方法，您已经成功地在 Symfony 5 应用程序中实现了同步和异步邮件发送的灵活控制：
- 异步邮件：通过创建自定义的 EmailAsync 消息和 EmailAsyncHandler 处理器，并将其路由到 Messenger 的异步传输层。您的服务通过 MessageBusInterface 调度这些消息。
- 同步邮件：直接通过 MailerInterface 发送邮件，不涉及 Messenger，确保邮件立即发送。
注意事项：
-
Messenger Worker：为了处理异步邮件，您需要运行 Messenger worker。在生产环境中，这通常通过 Supervisor 或 Systemd 等进程管理器来管理：
php bin/console messenger:consume async
- 错误处理与重试：Messenger 组件提供了强大的错误处理和重试机制。您可以配置失败策略，例如在邮件发送失败时自动重试或将失败的消息发送到不同的队列进行人工审查。
- 发件人地址：在实际应用中，发件人地址通常应从配置文件（如 services.yaml 或 parameters.yaml）中获取，而不是硬编码在代码中。
- 模板路径：确保您的 Twig 模板路径正确无误。
- 扩展性：这种模式具有良好的扩展性。如果未来有其他需要异步处理的任务，您也可以采用类似的消息和处理器模式。
通过这种清晰的分离，您的应用程序将能够更有效地管理邮件发送，提升用户体验并优化系统资源利用。
