使用 Mailer 发送电子邮件

1
2
3
4
5
6
7
8
9
10
11
12
13

use Symfony\Component\Mailer\Transport\Smtp\Auth\XOAuth2Authenticator;
use Symfony\Component\Mailer\Transport\Smtp\EsmtpTransport;

// Choose one of these two options:

// Option 1: pass the authenticators to the constructor
$transport = new EsmtpTransport(
    host: 'oauth-smtp.domain.tld',
    authenticators: [new XOAuth2Authenticator()]
);

// Option 2: call a method to redefine the authenticators
$transport->setAuthenticators([new XOAuth2Authenticator()]);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// src/Mailer/AcmeTransportFactory.php
final class AcmeTransportFactory extends AbstractTransportFactory
{
    public function create(Dsn $dsn): TransportInterface
    {
        // parse the given DSN, extract data/credentials from it
        // and then, create and return the transport
    }

    protected function getSupportedSchemes(): array
    {
        // this supports DSN starting with `acme://`
        return ['acme'];
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

// ...
use Symfony\Component\Mime\Address;

$email = (new Email())
    // email address as a simple string
    ->from('[email protected]')

    // non-ASCII characters are supported both in the local part and the domain;
    // if the SMTP server doesn't support this feature, you'll see an exception
    ->from('jânë.dœ@ëxãmplę.com')

    // email address as an object
    ->from(new Address('[email protected]'))

    // defining the email address and name as an object
    // (email clients will display the name)
    ->from(new Address('[email protected]', 'Fabien'))

    // defining the email address and name as a string
    // (the format must match: 'Name <[email protected]>')
    ->from(Address::create('Fabien Potencier <[email protected]>'))

    // ...
;

1
2
3
4
5
6
7
8
9
10
11
12

$email = (new Email())
    ->getHeaders()
        // this non-standard header tells compliant autoresponders ("email holiday mode")
        // to not reply to this message because it's an automated email
        ->addTextHeader('X-Auto-Response-Suppress', 'OOF, DR, RN, NRN, AutoReply')

        // use an array if you want to add a header with multiple values
        // (for example in the "References" or "In-Reply-To" header)
        ->addIdHeader('References', ['[email protected]', '[email protected]'])

        // ...
;

1
2
3
4
5
6
7
8
9
10

$email = (new Email())
    // ...
    // simple contents defined as a string
    ->text('Lorem ipsum...')
    ->html('<p>Lorem ipsum...</p>')

    // attach a file stream
    ->text(fopen('/path/to/emails/user_signup.txt', 'r'))
    ->html(fopen('/path/to/emails/user_signup.html', 'r'))
;

1
2
3
4
5
6
7
8
9
10
11
12

use Symfony\Component\Mime\Part\DataPart;
use Symfony\Component\Mime\Part\File;
// ...

$email = (new Email())
    // ...
    ->addPart(new DataPart(new File('/path/to/documents/terms-of-use.pdf')))
    // optionally you can tell email clients to display a custom name for the file
    ->addPart(new DataPart(new File('/path/to/documents/privacy.pdf'), 'Privacy Policy'))
    // optionally you can provide an explicit MIME type (otherwise it's guessed)
    ->addPart(new DataPart(new File('/path/to/documents/contract.doc'), 'Contract', 'application/msword'))
;

1
2
3
4
5
6
7
8
9
10
11

$email = (new Email())
    // ...
    ->addPart((new DataPart(fopen('/path/to/images/logo.png', 'r'), 'logo', 'image/png'))->asInline())
    ->addPart((new DataPart(new File('/path/to/images/signature.gif'), 'footer-signature', 'image/gif'))->asInline())

    // reference images using the syntax 'cid:' + "image embed name"
    ->html('<img src="cid:logo"> ... <img src="cid:footer-signature"> ...')

    // use the same syntax for images included as HTML background images
    ->html('... <div background="cid:footer-signature"> ... </div> ...')
;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

use Symfony\Bridge\Twig\Mime\TemplatedEmail;

$email = (new TemplatedEmail())
    ->from('[email protected]')
    ->to(new Address('[email protected]'))
    ->subject('Thanks for signing up!')

    // path of the Twig template to render
    ->htmlTemplate('emails/signup.html.twig')

    // change locale used in the template, e.g. to match user's locale
    ->locale('de')

    // pass variables (name => value) to the template
    ->context([
        'expiration_date' => new \DateTime('+7 days'),
        'username' => 'foo',
    ])
;

1
2
3
4
5
6
7
8
9
10
11

use Symfony\Component\Mime\Crypto\SMimeEncrypter;
use Symfony\Component\Mime\Email;

$email = (new Email())
    ->from('[email protected]')
    // ...
    ->html('...');

$encrypter = new SMimeEncrypter('/path/to/certificate.crt');
$encryptedEmail = $encrypter->encrypt($email);
// now use the Mailer component to send this $encryptedEmail instead of the original email

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

$firstEmail = (new Email())
    // ...
    ->to('[email protected]');

$secondEmail = (new Email())
    // ...
    ->to('[email protected]');

// the second optional argument of SMimeEncrypter defines which encryption algorithm is used
// (it must be one of these constants: https://php.ac.cn/manual/en/openssl.ciphers.php)
$encrypter = new SMimeEncrypter([
    // key = email recipient; value = path to the certificate file
    '[email protected]' => '/path/to/first-certificate.crt',
    '[email protected]' => '/path/to/second-certificate.crt',
]);

$firstEncryptedEmail = $encrypter->encrypt($firstEmail);
$secondEncryptedEmail = $encrypter->encrypt($secondEmail);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\Mailer\Event\MessageEvent;
use Symfony\Component\Mime\Email;

public function onMessage(MessageEvent $event): void
{
    $message = $event->getMessage();
    if (!$message instanceof Email) {
        return;
    }
    // do something with the message (logging, ...)

    // and/or add some Messenger stamps
    $event->addStamp(new SomeMessengerStamp());
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\Mailer\Event\FailedMessageEvent;
use Symfony\Component\Mailer\Exception\TransportExceptionInterface;

public function onMessage(FailedMessageEvent $event): void
{
    // e.g you can get more information on this error when sending an email
    $error = $event->getError();
    if ($error instanceof TransportExceptionInterface) {
        $error->getDebug();
    }

    // do something with the message
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

// tests/Controller/MailControllerTest.php
namespace App\Tests\Controller;

use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;

class MailControllerTest extends WebTestCase
{
    public function testMailIsSentAndContentIsOk(): void
    {
        $client = static::createClient();
        $client->request('GET', '/mail/send');
        $this->assertResponseIsSuccessful();

        $this->assertEmailCount(1); // use assertQueuedEmailCount() when using Messenger

        $email = $this->getMailerMessage();

        $this->assertEmailHtmlBodyContains($email, 'Welcome');
        $this->assertEmailTextBodyContains($email, 'Welcome');
    }
}