Symfony 5 邮件发送：同步与异步模式的实践指南

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

// 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 = 'noreply@example.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;
    }
}

// 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 用接口

// Symfony 5 兼容写法：实现 MessageHandlerInterface
// use Symfony\Component\Messenger\Handler\MessageHandlerInterface;
// class EmailAsyncHandler implements MessageHandlerInterface

#[AsMessageHandler] // Symfony 6+ 推荐使用属性
class EmailAsyncHandler
{
    private MailerInterface $mailer;

    public function __construct(MailerInterface $mailer)
    {
        $this->mailer = $mailer;
    }

    public function __invoke(EmailAsync $emailAsync): void
    {
        $emailToSend = (new TemplatedEmail())
            ->from(new Address($emailAsync->getSenderEmail()))
            ->to(new Address($emailAsync->getRecipient()))
            ->subject($emailAsync->getSubject())
            ->htmlTemplate($emailAsync->getBodyHtmlTemplate())
            ->textTemplate($emailAsync->getBodyTextTemplate())
            ->context($emailAsync->getContext());

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

# config/packages/messenger.yaml
framework:
    messenger:
        transports:
            async: '%env(MESSENGER_TRANSPORT_DSN)%'
            # 可以有其他传输层，例如失败重试队列
            # failed: 'doctrine://default?queue_name=failed'

        routing:
            # 将我们自定义的 EmailAsync 消息路由到异步传输层
            'App\Message\EmailAsync': async
            # 确保没有将 Symfony\Component\Mailer\Messenger\SendEmailMessage 路由到异步
            # 否则所有邮件都将异步化，即使你只想同步发送
            # 'Symfony\Component\Mailer\Messenger\SendEmailMessage': async # 移除或注释此行

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

    public function sendAsyncEmail(
        string $subject,
        string $htmlTemplate,
        ?string $textTemplate,
        string $to,
        array $context = [],
        string $from = 'noreply@example.com'
    ): void {
        $emailAsync = new EmailAsync($subject, $htmlTemplate, $textTemplate, $to, $context, $from);
        $this->bus->dispatch($emailAsync);
    }
}

// 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 $defaultFromEmail; // 可以从配置中注入

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

    public function sendSyncEmail(
        string $subject,
        string $htmlTemplate,
        ?string $textTemplate,
        string $to,
        array $context = [],
        ?string $from = null
    ): void {
        $email = (new TemplatedEmail())
            ->from(new Address($from ?? $this->defaultFromEmail))
            ->to(new Address($to))
            ->subject($subject)
            ->htmlTemplate($htmlTemplate)
            ->textTemplate($textTemplate)
            ->context($context);

        $this->mailer->send($email); // 这将是同步发送
    }
}