在 Symfony 5 中灵活实现同步与异步邮件发送

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

<?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;
    }
}

<?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);
    }
}

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 # 或者完全不配置此项

<?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);
    }
}

<?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);
    }
}