Symfony 5 中实现邮件同步与异步发送的策略-php教程-PHP中文网

Symfony 5 中实现邮件同步与异步发送的策略

本文旨在指导读者如何在 symfony 5 应用程序中灵活实现邮件的同步与异步发送。通过利用 symfony messenger 组件，创建自定义消息类和对应的处理器，并进行精确的路由配置，可以有效分离异步邮件逻辑，同时确保常规邮件发送的同步性，避免重复发送问题，从而优化用户体验和系统性能。

在现代 Web 应用中，邮件发送通常是耗时操作，将其异步化可以显著提升用户体验和应用响应速度。Symfony 5 及其更高版本通过集成 Mailer 和 Messenger 组件，提供了强大的邮件发送能力，并支持灵活的同步与异步处理。本文将详细介绍如何配置和实现这一机制，确保您能够根据业务需求选择合适的邮件发送模式。

理解 Symfony Messenger 与邮件发送机制

Symfony Mailer 组件在发送邮件时，默认会生成一个 Symfony\Component\Mailer\Messenger\SendEmailMessage 消息，并将其分发到 Messenger 总线。如果您的 Messenger 配置中将此消息路由到异步传输，那么所有通过 MailerInterface::send() 方法发送的邮件都将被异步处理。这在某些场景下是期望行为，但在需要同时支持同步和异步邮件发送时，则需要更精细的控制。

例如，如果您的 messenger.yaml 配置如下：

# config/packages/messenger.yaml
framework:
    messenger:
        transports:
            async: '%env(MESSENGER_TRANSPORT_DSN)%'
        routing:
            'Symfony\Component\Mailer\Messenger\SendEmailMessage': async

登录后复制

此时，所有邮件都将通过 async 传输进行异步发送。为了实现选择性异步，我们需要引入自定义消息。

步骤一：创建异步邮件消息类

为了将邮件发送的具体数据封装起来，并使其能够在 Messenger 总线中传递，我们需要定义一个自定义的消息类。这个类将包含构建 TemplatedEmail 所需的所有信息。

// src/Message/EmailAsync.php
<?php

namespace App\Message;

class EmailAsync
{
    private string $subject;
    private string $bodyHtmlTemplate; // 对应 Twig 模板路径
    private string $bodyTextTemplate; // 对应纯文本模板路径
    private string $recipient;
    private array $context = [];
    private ?string $sender = null; // 可选，如果需要自定义发件人

    public function __construct(
        string $subject,
        string $bodyHtmlTemplate,
        string $bodyTextTemplate,
        string $recipient,
        array $context = [],
        ?string $sender = null
    ) {
        $this->subject = $subject;
        $this->bodyHtmlTemplate = $bodyHtmlTemplate;
        $this->bodyTextTemplate = $bodyTextTemplate;
        $this->recipient = $recipient;
        $this->context = $context;
        $this->sender = $sender;
    }

    // 为所有属性生成公共的 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 getSender(): ?string
    {
        return $this->sender;
    }
}

登录后复制

步骤二：实现异步邮件消息处理器

消息处理器负责接收特定类型的消息，并执行相应的业务逻辑。对于 EmailAsync 消息，其处理器将使用 MailerInterface 来实际构建并发送邮件。

// 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\Attribute\AsMessageHandler; // Symfony 6+ 推荐，Symfony 5 仍可使用 MessageHandlerInterface

#[AsMessageHandler] // Symfony 6.0+ 推荐，替代 MessageHandlerInterface
class EmailAsyncHandler // implements MessageHandlerInterface // Symfony 5 兼容写法
{
    private MailerInterface $mailer;
    private string $defaultSenderEmail; // 从配置中获取默认发件人

    public function __construct(MailerInterface $mailer, string $defaultSenderEmail = 'noreply@example.com')
    {
        $this->mailer = $mailer;
        $this->defaultSenderEmail = $defaultSenderEmail;
    }

    public function __invoke(EmailAsync $emailAsync): void
    {
        $sender = $emailAsync->getSender() ?? $this->defaultSenderEmail;

        $emailToSend = (new TemplatedEmail())
            ->from(new Address($sender))
            ->to(new Address($emailAsync->getRecipient()))
            ->subject($emailAsync->getSubject())
            ->htmlTemplate($emailAsync->getBodyHtmlTemplate())
            ->textTemplate($emailAsync->getBodyTextTemplate())
            ->context($emailAsync->getContext());

        $this->mailer->send($emailToSend);
    }
}

登录后复制

注意事项：

在 Symfony 6.0 及更高版本中，推荐使用 #[AsMessageHandler] 属性来标记处理器，替代 implements MessageHandlerInterface。
defaultSenderEmail 可以通过服务配置（例如 services.yaml）注入，确保发件人地址的灵活性。

步骤三：配置 Messenger 路由

现在，我们需要告诉 Symfony Messenger，当它遇到 App\Message\EmailAsync 类型的消息时，应该将其路由到 async 传输。同时，非常重要的一点是，不要将 Symfony\Component\Mailer\Messenger\SendEmailMessage 路由到异步传输，以确保通过 MailerInterface::send() 直接发送的邮件保持同步。

MedPeer科研绘图

生物医学领域的专业绘图解决方案，告别复杂绘图，专注科研创新

166

查看详情

# config/packages/messenger.yaml
framework:
    messenger:
        transports:
            # 定义异步传输，通常使用 DSN 从环境变量获取连接字符串
            async: '%env(MESSENGER_TRANSPORT_DSN)%'

        routing:
            # 将自定义的 EmailAsync 消息路由到异步传输
            'App\Message\EmailAsync': async

            # 保持 Symfony\Component\Mailer\Messenger\SendEmailMessage 不被路由到异步
            # 这样，通过 MailerInterface::send() 直接发送的邮件将默认同步处理
            # 如果不在这里明确指定，它会走默认的同步处理流程。
            # 如果需要对所有邮件做统一处理，可以考虑在这里添加一个 'sync' 传输，
            # 或者干脆不配置它，让其走默认的同步处理。
            # 'Symfony\Component\Mailer\Messenger\SendEmailMessage': sync # 示例：明确路由到同步传输

登录后复制

通过上述配置，只有 EmailAsync 消息才会被推入异步队列。而任何直接调用 MailerInterface::send() 发送的 TemplatedEmail，由于其对应的 SendEmailMessage 未被路由到异步传输，将会在当前请求中同步发送。

步骤四：在服务中实现同步与异步发送

现在，您可以在应用程序的不同服务中根据需要选择同步或异步发送邮件。

1. 异步发送邮件

在需要异步发送邮件的服务中，您应该注入 MessageBusInterface，并分发 EmailAsync 消息。

// src/Service/MailManagerAsync.php
<?php

namespace App\Service;

use App\Message\EmailAsync;
use Symfony\Component\Messenger\MessageBusInterface;

class MailManagerAsync
{
    private MessageBusInterface $bus;
    private string $defaultSenderEmail; // 注入或硬编码默认发件人

    public function __construct(MessageBusInterface $bus, string $defaultSenderEmail = 'noreply@example.com')
    {
        $this->bus = $bus;
        $this->defaultSenderEmail = $defaultSenderEmail;
    }

    /**
     * 异步发送邮件
     *
     * @param string $subject 邮件主题
     * @param string $bodyHtmlTemplate HTML 模板路径
     * @param string $bodyTextTemplate 纯文本模板路径
     * @param string $to 收件人邮箱
     * @param array $context 传递给模板的上下文数据
     * @param string|null $sender 可选，自定义发件人邮箱
     */
    public function sendAsyncEmail(
        string $subject,
        string $bodyHtmlTemplate,
        string $bodyTextTemplate,
        string $to,
        array $context = [],
        ?string $sender = null
    ): void {
        $emailAsync = new EmailAsync(
            $subject,
            $bodyHtmlTemplate,
            $bodyTextTemplate,
            $to,
            $context,
            $sender ?? $this->defaultSenderEmail
        );
        $this->bus->dispatch($emailAsync);
    }
}

登录后复制

2. 同步发送邮件

对于需要同步发送的邮件，您只需注入 MailerInterface 并直接调用其 send() 方法即可。

// 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 = 'noreply@example.com')
    {
        $this->mailer = $mailer;
        $this->defaultSenderEmail = $defaultSenderEmail;
    }

    /**
     * 同步发送邮件
     *
     * @param string $subject 邮件主题
     * @param string $bodyHtmlTemplate HTML 模板路径
     * @param string $bodyTextTemplate 纯文本模板路径
     * @param string $to 收件人邮箱
     * @param array $context 传递给模板的上下文数据
     * @param string|null $sender 可选，自定义发件人邮箱
     */
    public function sendSyncEmail(
        string $subject,
        string $bodyHtmlTemplate,
        string $bodyTextTemplate,
        string $to,
        array $context = [],
        ?string $sender = null
    ): void {
        $email = (new TemplatedEmail())
            ->from(new Address($sender ?? $this->defaultSenderEmail))
            ->to(new Address($to))
            ->subject($subject)
            ->htmlTemplate($bodyHtmlTemplate)
            ->textTemplate($bodyTextTemplate)
            ->context($context);

        $this->mailer->send($email);
    }
}

登录后复制

总结与注意事项

通过上述方法，您已经成功在 Symfony 应用程序中实现了邮件的同步与异步发送分离：

自定义消息和处理器：这是实现选择性异步的关键。它允许您精确控制哪些邮件流程应通过 Messenger 队列处理。
Messenger 路由配置：只将自定义的异步消息路由到异步传输，而让 MailerInterface::send() 产生的默认消息（SendEmailMessage）保持同步处理，避免了重复发送和不必要的队列化。
服务分离：创建不同的服务（或在同一服务中提供不同方法）来处理同步和异步邮件发送，使得代码结构更清晰，易于维护。

重要提示：

Messenger 消费者：对于异步邮件，您需要运行 Messenger 消费者进程来处理队列中的消息。在生产环境中，这通常通过 Supervisor 或 Systemd 等工具管理：
```
php bin/console messenger:consume async --time-limit=3600
```
登录后复制
错误处理：在消息处理器中，应考虑增加健壮的错误处理机制，例如日志记录、重试策略或将失败消息发送到单独的失败队列。
环境变量：确保 MESSENGER_TRANSPORT_DSN 环境变量已正确配置，指向您的消息队列服务（如 RabbitMQ, Redis, Doctrine 等）。
默认发件人：建议将默认发件人邮箱配置为应用程序参数，并在服务中注入，以提高灵活性。

遵循这些步骤和最佳实践，您将能够在 Symfony 应用中高效且灵活地管理邮件发送，从而提升整体性能和可靠性。

以上就是Symfony 5 中实现邮件同步与异步发送的策略的详细内容，更多请关注php中文网其它相关文章！

大家都在看：

php检查一维数组方法_php判断数组维度技巧教程【指南】 php查询结果放数组里_php数据库结果转数组操作【解析】服务器php网站源码怎么拿_取服务器php网站源码方法 php后台源码怎么获取_php后台源码获取合法渠道与权限设置【指南】 php处理二维数组转换操作_php多维数组数据处理技巧【指南】