Использование встроенного транспорта

Использование стороннего транспорта

Instead of using your own SMTP server or sendmail binary, you can send emails via a 3rd party provider. Mailer supports several - install whichever you want:

Каждая библиотека содержит рецепт Symfony Flex , который будет добавлять пример конфигурации в ваш файл .env. Например, представьте, что вы хотите использовать SendGrid. Для начала, установите его:

1

$ composer require symfony/sendgrid-mailer

Теперь у вас будет новая строка в вашем файле .env, которую вы можете раскомментировать:

1
2

# .env
MAILER_DSN=sendgrid://KEY@default

MAILER_DSN - это не настоящий адрес: это удобный формат, который сгружает большую часть работы конфигурации почтовой программе. Схема sendgrid активирует поставщика SendGrid, который вы только что установили, который знает все о том, как доставить сообщения через SendGrid. Единственное, что вам нужно изменить - заполнитель KEY.

Какждый поставщик имеет разные переменные окружения, которые Mailer использует для конфигурации настоящего протокла, адрса и аутентификации для отправки. Некоторые также имеют опции, которые можно сконфигурировать с параметрами запроса в конце MAILER_DSN - как, например, ?region= для Amazon SES или Mailgun. Некоторые поставщики поддерживают отправку через http, api или smtp. Symfony выбирает лучший доступный транспорт, но вы можете форсировать использование одного из них:

1
2
3

# .env
# форсировать использование SMTP вместо HTTP (который стоит по умолчанию)
MAILER_DSN=sendgrid+smtp://$SENDGRID_KEY@default

Эта таблица отображает полный список доступных форматов DSN для каждого стороннего поставщика:

1
2
3

# .env
MAILER_DSN=mailgun+https://KEY:DOMAIN@requestbin.com
MAILER_DSN=mailgun+https://KEY:DOMAIN@requestbin.com:99

Высокая доступность

Mailer Symfony поддерживает высокую доступность через технику под названием "failover", чтобы гарантировать, что письма будут отправлены, даже если один сервер потерпит неудачу.

Транспорт failover сконфигурирован с двумя или более транспортами и ключевым словом failover:

1

MAILER_DSN="failover(postmark+api://ID@default sendgrid+smtp://KEY@default)"

Транспорт failover начинает с использования первого транспорта, и если он терпит неудачу, он повторно попробует отправку со следующим транспортом, пока один из них не приведет к успеху (или пока они все не потерпят неудачу).

Балансировка нагрузки

Mailer Symfony поддерживает балансировку нагрузки через технику под названием "round-robin" для распределения рабочей нагрузки отправки писем по нескольким транспортам.

Транспорт round-robin сконфигурирован с двумя или более транспортами и ключевым словом roundrobin:

1

MAILER_DSN="roundrobin(postmark+api://ID@default sendgrid+smtp://KEY@default)"

Транспорт round-robin начинает с рандомно выбранного транспорта, а затем переключается на следующий доступный трансфер для каждого последующего письма.

Как и с транспортом failover, round-robin повторно пытается совершить отправку, пока транспорт не добьется успеха (или пока все не потерпят неудачу). В отличие от транспорта failover, он распространяет нагрузку по всем своим транспортам.

Верификаиця точек TLS

По умолчанию, транспорт SMTP выполняет верификацию точек TLS. Это поведение конфигурируется опцией verify_peer. Хотя и не рекомендуется отключать верификацию из соображений безопасности, это может быть полезно при разработке приложения или при использовании самозаверенного сертификата:

1

$dsn = 'smtp://user:pass@smtp.example.com?verify_peer=0';

Другие опции

command

Команда для выполнения транспортом sendmail:

1

$dsn = 'sendmail://default?command=/usr/sbin/sendmail%20-oi%20-t'

local_domain

Имя домена для использования в команде HELO:

1

$dsn = 'smtps://smtp.example.com?local_domain=example.org'

restart_threshold

Максимальное количество сообщений для отправки до перезагрузки транспорта. Может быть использована вместе с restart_threshold_sleep:

1

$dsn = 'smtps://smtp.example.com?restart_threshold=10&restart_threshold_sleep=1'

restart_threshold_sleep

Количество секунд сна между остановкой и перезагрузкой транспорта. Часто сочетается с restart_threshold:

1

$dsn = 'smtps://smtp.example.com?restart_threshold=10&restart_threshold_sleep=1'

ping_threshold

Минимальное количество секунд между двумя сообщениями, необходимое для пинга серверу:

1

$dsn = 'smtps://smtp.example.com?ping_threshold=200'

max_per_second

Количество сообщений, которые нужно отправлять за секунду (0, чтобы отключить это ограничение):

1

$dsn = 'smtps://smtp.example.com?max_per_second=2'

6.2

Опция max_per_second была представлена в Symfony 6.2.

Адреса электронной почты

Все методы, требующие адресов электронной почты (from(), to(), etc.), принимают как строки, так и объекты адресов:

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

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

$email = (new Email())
    // адрес почты как обычная строка
    ->from('fabien@example.com')

    // адрес почты как объект
    ->from(new Address('fabien@example.com'))

    // определение адреса и имени почты как объекта
    // (почтовые клиенты отобразят имя)
    ->from(new Address('fabien@example.com', 'Fabien'))

    // определение адреса и имени почты как строки
    // (формат должен соответствовать: 'Имя <email@example.com>')
    ->from(Address::create('Fabien Potencier <fabien@example.com>'))

    // ...
;

Используйте методы addTo(), addCc(), или addBcc(), чтобы добавить больше адресов:

1
2
3
4
5
6
7
8

$email = (new Email())
    ->to('foo@example.com')
    ->addTo('bar@example.com')
    ->cc('cc@example.com')
    ->addCc('cc2@example.com')

    // ...
;

Как вариант, вы можете передать несколько адресов каждому методу:

1
2
3
4
5
6
7
8

$toAddresses = ['foo@example.com', new Address('bar@example.com')];

$email = (new Email())
    ->to(...$toAddresses)
    ->cc('cc1@example.com', 'cc2@example.com')

    // ...
;

Заголовки сообщений

Сообщения содержат некоторое количество полей заголовков, чтобы описать их содержание. Symfony устанавливает все заголовки автоматически, но вы также можете установить собственные заголовки. Существуют разные типы заголовков (заголовок Id, заголовок Mailbox, заголовок Date и т.д.), но в большинстве случаев вы будете устанавливать текстовые заголовки:

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

$email = (new Email())
    ->getHeaders()
        // этот заголовок сообщает авто-ответчикам ("режим отпуска электронной почты")
        // не отвечать на это сообщение, так как это автоматизированное письмо
        ->addTextHeader('X-Auto-Response-Suppress', 'OOF, DR, RN, NRN, AutoReply');

        // использовать массив, если вы хотите добавить заголовок с несколькими значениями
        // (например, в заголовке "References" или "In-Reply-To")
        ->addIdHeader('References', ['123@example.com', '456@example.com'])

        // ...
;

Содержание сообщения

Текстовое и HTML-содержание сообщений писем может быть строками (обычно в результате отображения какого-то шаблона), или PHP-источниками:

1
2
3
4
5
6
7
8
9
10

$email = (new Email())
    // ...
    // простое содержание, определенное как строка
    ->text('Lorem ipsum...')
    ->html('<p>Lorem ipsum...</p>')

    // прикрепить поток файлов
    ->text(fopen('/path/to/emails/user_signup.txt', 'r'))
    ->html(fopen('/path/to/emails/user_signup.html', 'r'))
;

Прикрепление файлов

Используйте метод attachFromPath(), чтобы прикреплять файлы, существующие в вашей файловой системе:

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')))
    // опционально, вы можете сообщить клиентам почты, чтобы они отображали пользовательское имя файла
    ->attachFromPath('/path/to/documents/privacy.pdf', 'Privacy Policy')
    // опционально, вы можете предоставить ясный тип MIME (в другом случае он будет угадываться)
    ->attachFromPath('/path/to/documents/contract.doc', 'Contract', 'application/msword')
;

Как вариант, вы можете использовать метод attach(), чтобы прикреплять содержание из потока:

1
2
3
4

$email = (new Email())
    // ...
    ->addPart(new DataPart(fopen('/path/to/documents/contract.doc', 'r')))
;

Встраивание изображений

Если вы хотите отобразить изображения внутри вашего письма, вы должны их встроить, а не добавлять их как вложения. При использовании Twig для отображения содержания письма, как объясняется далее в этой статье , изображения встраиваются автоматически. В другом случае, вам нужно будет встроить их вручную.

Для начала, используйте метод embed() или embedFromPath(), чтобы добавить изображение из файла или потока:

1
2
3
4
5
6
7

$email = (new Email())
    // ...
    // получить содержание изображение из PHP-источника
    ->embed(fopen('/path/to/images/logo.png', 'r'), 'logo')
    // получить содержание изображение из существующего файла
    ->embedFromPath('/path/to/images/signature.gif', 'footer-signature')
;

Используйте метод asInline(), чтобы встроить содержание, вместо того, чтобы прикреплять его.

Второй необязательный аругмент обоих методов - это имя изображения ("Content-ID" по стандарту MIME). Его значение - это произвольная строка, используемая позже для того, чтобы ссылаться на изображение внутри HTML содержания:

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())

    // сошлитесь на изображения, используя синтаксис 'cid:' + "image embed name"
    ->html('<img src="cid:logo"> ... <img src="cid:footer-signature"> ...')

    // использовать тот же синтаксис для изображений, добавленных как фоновые изображения HTML
    ->html('... <div background="cid:footer-signature"> ... </div> ...')
;

HTML-содержание

Чтобы определить содержание вашего письма с Twig, используйте класс TemplatedEmail. Этот класс расширяет нормальный класс Email, но добавляет некоторые новые методы для шаблонов Twig:

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

use Symfony\Bridge\Twig\Mime\TemplatedEmail;

$email = (new TemplatedEmail())
    ->from('fabien@example.com')
    ->to(new Address('ryan@example.com'))
    ->subject('Thanks for signing up!')

    // путь шаблона Twig для отображения
    ->htmlTemplate('emails/signup.html.twig')

    // передайте переменные (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
12

{# templates/emails/signup.html.twig #}
<h1>Welcome {{ email.toName }}!</h1>

<p>
    You signed up as {{ username }} the following email:
</p>
<p><code>{{ email.to[0].address }}</code></p>

<p>
    <a href="#">Click here to activate your account</a>
    (this link is valid until {{ expiration_date|date('F jS') }})
</p>

Шаблон Twig имеет доступ к любым параметрам, переданным в метод context() класса TemplatedEmail и также специальной переменной под названием email, которая является экземпляром WrappedTemplatedEmail.

Текстовое содержание

Когда текстовое содержание TemplatedEmail не определено ясно, почтовая программа автоматически сгенерирует его, преобразовав HTML-содержание в текст. Если у вас в приложении установлен league/html-to-markdown, он использует это для превращения HTML в разметку (чтобы текстовое письмо имело визуально привлекательный вид). В другом случае, он применяет PHP-функцию strip_tags к изначальному HTML-содержанию.

Если вы хотите определить текстовое содержание самостоятельно, используйте метод text(), разъясненный в предыдущих разделах, или метод textTemplate(), предоставленный классом TemplatedEmail:

1
2
3
4
5
6
7
8
9

+ use Symfony\Bridge\Twig\Mime\TemplatedEmail;

$email = (new TemplatedEmail())
    // ...

    ->htmlTemplate('emails/signup.html.twig')
+     ->textTemplate('emails/signup.txt.twig')
    // ...
;

Встраивание изображений

Вместо того, чтобы разбираться с синтаксисом <img src="cid: ...">, который разъяснялся в предыдущих разделах, при использовании Twig для отображения содержания письма, вы можете сослаться на файлы изображений, как обычно. Для начала, чтобы упростить все, определите пространство имен Twig под названием images, которое указывает на тот каталог, где хранятся ваши изображения:

1
2
3
4
5
6
7

# config/packages/twig.yaml
twig:
    # ...

    paths:
        # укажите туда, где живут ваши изображения
        '%kernel.project_dir%/assets/images': images

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

<!-- config/packages/twig.xml -->
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:twig="http://symfony.com/schema/dic/twig"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/twig https://symfony.com/schema/dic/twig/twig-1.0.xsd">

    <twig:config>
        <!-- ... -->

        <!-- укажите туда, где живут ваши изображения -->
        <twig:path namespace="images">%kernel.project_dir%/assets/images</twig:path>
    </twig:config>
</container>

1
2
3
4
5
6
7
8
9

// config/packages/twig.php
use Symfony\Config\TwigConfig;

return static function (TwigConfig $twig) {
    // ...

    // укажите туда, где живут ваши изображения
    $twig->path('%kernel.project_dir%/assets/images', 'images');
};

Теперь, используйте специального помощника Twig email.image(), чтобы встроить изображение в содержание письма:

1
2
3
4
5

{# '@images/' refers to the Twig namespace defined earlier #}
<img src="{{ email.image('@images/logo.png') }}" alt="Logo">

<h1>Welcome {{ email.toName }}!</h1>
{# ... #}

Встраивание CSS-стилей

Дизайн HTML-содержания письма очень отличается от дизайна обычной HTML-страницы. Для начала, большинство почтовых клиентов поддержвают только часть всех CSS-функций. Кроме того, популярные почтовые клиенты, вроде Gmail, не поддерживают определяющие стили внутри разделов <style> ... </style> и вы должны встроить все CSS-стили.

Встраивание CSS означает, что каждый HTML-тег должен определять атрибут style со всеми его CSS-стилями. Это может сильно запутать упорядочивание вашего CSS. Поэтому Twig предоставляет CssInlinerExtension, который автоматизирует все для вас. Установите его:

1

$ composer require twig/extra-bundle twig/cssinliner-extra

Расширение включается автоматически. Чтобы использовать его, оберните весь шаблон в фильтр inline_css:

1
2
3
4
5
6
7
8
9
10
11

{% apply inline_css %}
    <style>
        {# здесь, определите ваши СSS-стили, как обычно #}
        h1 {
            color: #333;
        }
    </style>

    <h1>Welcome {{ email.toName }}!</h1>
    {# ... #}
{% endapply %}

1
2
3
4

{% apply inline_css(source('@styles/email.css')) %}
    <h1>Welcome {{ username }}!</h1>
    {# ... #}
{% endapply %}

1
2
3
4
5
6
7

# config/packages/twig.yaml
twig:
    # ...

    paths:
        # укажите туда, где живут ваши css-файлы
        '%kernel.project_dir%/assets/styles': styles

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

<!-- config/packages/twig.xml -->
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:twig="http://symfony.com/schema/dic/twig"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/twig https://symfony.com/schema/dic/twig/twig-1.0.xsd">

    <twig:config>
        <!-- ... -->

        <!-- укажите туда, где живут ваши css-файлы -->
        <twig:path namespace="styles">%kernel.project_dir%/assets/styles</twig:path>
    </twig:config>
</container>

1
2
3
4
5
6
7
8
9

// config/packages/twig.php
use Symfony\Config\TwigConfig;

return static function (TwigConfig $twig) {
    // ...

    // укажите туда, где живут ваши css-файлы
    $twig->path('%kernel.project_dir%/assets/styles', 'styles');
};

Отображение содержания с разметкой

Twig предоставляет другое расширение под названием MarkdownExtension, которое позволяет вам определять содержание писем с использованием синтаксиса Markdown. Чтобы использовать его, установите расширение и библиотеку конверсий Markdown (расширение совместимо с несколькими популярными библиотеками):

1
2

# вместо league/commonmark, вы также можете использовать erusev/parsedown или michelf/php-markdown
$ composer require twig/extra-bundle twig/markdown-extra league/commonmark

Расширение добавляет фильтр markdown_to_html, который вы можете использовать, чтобы преобразовывать части или все содержание письма из Markdown в HTML:

1
2
3
4
5
6
7
8
9

{% apply markdown_to_html %}
    Welcome {{ email.toName }}!
    ===========================

    Вы подписались на наш сайт, используя следующий адрес электронной почты:
    `{{ email.to[0].address }}`

    [Нажмите здесь, чтобы активировать ваш аккаунт]({{ url('...') }})
{% endapply %}

Язык шаблонизации писем Inky

Создание писем с прекрасным дизайном, которые работают в каждом почтовом клиенте, настолько сложно, что существуют целые фреймворки HTML/CSS, посвященные этому. Один из наиболее популярных фреймворков называется`Inky`_. Он определяет синтаксиси, основываясь на тегах типа HTML, которые позже преобразуются в настоящий HTML-код и отправляются пользователям:

1
2
3
4
5
6

<!-- упрощенный пример синтаксиса Inky -->
<container>
    <row>
        <columns>This is a column.</columns>
    </row>
</container>

Twig предоставляет интегракцию с Inky через InkyExtension. Для начала, установите расширение в вашем приложении:

1

$ composer require twig/extra-bundle twig/inky-extra

Расширение добавляет фильтр inky_to_html, которые может быть использован для преображения частей или всего содержания письма из Inky в HTML:

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

{% apply inky_to_html %}
    <container>
        <row class="header">
            <columns>
                <spacer size="16"></spacer>
                <h1 class="text-center">Welcome {{ email.toName }}!</h1>
            </columns>

            {# ... #}
        </row>
    </container>
{% endapply %}

Вы можете скомбинировать все фильтры, чтобы создать сложные сообщения писем:

1
2
3

{% apply inky_to_html|inline_css(source('@styles/foundation-emails.css')) %}
    {# ... #}
{% endapply %}

Это использует пространство имен стилей Twig , которое мы создали ранее. Вы могли бы, к примеру, скачать файл foundation-emails.css прямо с GitHub и сохранить его в assets/styles.

Цифровая подпись сообщений

При добавлении цифровой подписи к сообщению, генерируется криптографический хеш для всего содержания сообщения (включая вложения). Этот хеш добавляется как вложение, чтобы получатель мог валидировать целосность полученного сообщения. Однако, содержание изначального сообщения остается читаемым для почтовых агентов, не поддерживающих подписанные сообщения, поэтому вы также должны зашифровать сообщение, если вы хотите скрыть его содержание.

Вы можете подписывать сообщения используя S/MIME или DKIM. В обоих случаях, сертификат и приватный ключ долшжны быть PEM-зашифрованы, и могут быть либо созданы с использованием, к примеру, OpenSSL, либо получены у официальной Сертификационной компании (CA). Получатель письма должен иметь сертификат CA в списке доверенных лиц, чтобы верифицировать подпись.

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

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

$email = (new Email())
    ->from('hello@example.com')
    // ...
    ->html('...');

$signer = new SMimeSigner('/path/to/certificate.crt', '/path/to/certificate-private-key.key');
// если приватный ключ имеет кодовую фразу, передайте ее как третий аргумент
// new SMimeSigner('/path/to/certificate.crt', '/path/to/certificate-private-key.key', 'the-passphrase');

$signedEmail = $signer->sign($email);
// теперь используйте компонент Mailer, чтобы отправить этот $signedEmail вместо изначального письма

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

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

$email = (new Email())
    ->from('hello@example.com')
    // ...
    ->html('...');

// первый аргумент: такой же, как openssl_pkey_get_private(), либо строка с содержанием
// приватного ключа, либо абсолютный путь к нему (с префиксом 'file://')
// второй и третий аргунметы: имя домена и "селектор", используемый для выполнения поиска DNS
// (селектор - это строка, используемая для указания на конкретную запись публичного ключа DKIM в вашей DNS)
$signer = new DkimSigner('file:///path/to/private-key.key', 'example.com', 'sf');
// если приватный ключ имеет кодовую фразу, передайте ее как пятый аргумент
// new DkimSigner('file:///path/to/private-key.key', 'example.com', 'sf', [], 'the-passphrase');

$signedEmail = $signer->sign($email);
// теперь используйте компонент Mailer, чтобы отправить этот $signedEmail вместо изначального письма

// подпись DKIM предоставляет множество опций конфигурации и объект помощника для их конфигурирования
use Symfony\Component\Mime\Crypto\DkimOptions;

$signedEmail = $signer->sign($email, (new DkimOptions())
    ->bodyCanon('relaxed')
    ->headerCanon('relaxed')
    ->headersToIgnore(['Message-ID'])
    ->toArray()
);

Шифрование сообщений

При шифровании сообщения, все сообщения (включая вложения) шифруется с использованием сертификата. Следовательно, только получатели, имеющие соответствующий приватный ключ, могут прочитать содержание изначального сообщения:

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('hello@example.com')
    // ...
    ->html('...');

$encrypter = new SMimeEncrypter('/path/to/certificate.crt');
$encryptedEmail = $encrypter->encrypt($email);
// теперь используйте компонент Mailer, чтобы отправить этот $encryptedEmail вместо изначального письма

Вы можете передать больше одного сертификата конструктору SMimeEncrypter, и он выберет соответствующий сертификат, в зависимости от опции To:

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

$firstEmail = (new Email())
    // ...
    ->to('jane@example.com');

$secondEmail = (new Email())
    // ...
    ->to('john@example.com');

// второй необязательный аргумент SMimeEncrypter определяет, какой алгоритм шифрования используется
// (должен быть одной из этих констант: https://www.php.net/manual/en/openssl.ciphers.php)
$encrypter = new SMimeEncrypter([
    // ключ = получатель письма; значение = путь к файлу сертификата
    'jane@example.com' => '/path/to/first-certificate.crt',
    'john@example.com' => '/path/to/second-certificate.crt',
]);

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

MessageEvent

Класс события: MessageEvent

MessageEvent позволяет изменять сообщение Mailer и конверт перед отправкой письма:

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

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;
    }
    // сделать что-то с сообщением
}

Выполните эту команду, чтобы узнать, какие слушатели зарегистрированы для этого события, и их приоритеты:

1

$ php bin/console debug:event-dispatcher "Symfony\Component\Mailer\Event\MessageEvent"

QueuingMessageEvent

Класс события: QueuingMessageEvent

QueuingMessageEvent позволяет добавлять некоторую логику до отправки сообщения в автобус Messenger (это событие не развёртывается, если автобус не сконфигуриорован); оно расширяет MessageEvent, чтобы разрешить добавление штампов Messenger к сообщению Messenger, отправленному автобусу:

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\QueuingMessageEvent;
use Symfony\Component\Mime\Email;

public function onMessage(QueuingMessageEvent $event): void
{
    $message = $event->getMessage();
    if (!$message instanceof Email) {
        return;
    }
    // сделать что-то с сообщением (записать лог, ...)

    // и/или добавить некоторые штампы Messenger
    $event->addStamp(new SomeMessengerStamp());
}

Это событие позволяет слушателям делать что-то до отправки сообщения в очеедь (вроде добавления штампов или записи логов), но любые изменения в сообщении или конверте, отбрасываются. Чтобы изменить сообщение или конверт, слушайте вместо этого MessageEvent.

Выполните эту команду, чтобы узнать, какие слушатели зарегистрированы для этого события, и их приоритеты:

1

$ php bin/console debug:event-dispatcher "Symfony\Component\Mailer\Event\QueuingMessageEvent"

SentMessageEvent

Класс события: SentMessageEvent

SentMessageEvent позволяет вам действовать в классе SentMessage, чтобы получить доступ к изначальному сообщению (getOriginalMessage()) и некоторой информамции отладки (getDebug()), вроде вызовов HTTP, сделанных транспортом HTTP, что полезно для отладки ошибок:

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

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\Mailer\Event\SentMessageEvent;
use Symfony\Component\Mailer\SentMessage;

public function onMessage(SentMessageEvent $event): void
{
    $message = $event->getMessage();
    if (!$message instanceof SentMessage) {
        return;
    }

    // сделать что-то с сообщением
}

Выполните эту команду, чтобы узнать, какие слушатели зарегистрированы для этого события, и их приоритеты:

1

$ php bin/console debug:event-dispatcher "Symfony\Component\Mailer\Event\SentMessageEvent"

FailedMessageEvent

Класс события: FailedMessageEvent

FailedMessageEvent позволяет действовать в изначальном сообщении в случае неудачи:

1
2
3
4
5
6
7
8
9
10

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

public function onMessage(FailedMessageEvent $event): void
{
    // например, вы можете получить больше информации об этой ошибке при отправке письма
    $event->getError();

    // сделать что-то с сообщением
}

Выполните эту команду, чтобы узнать, какие слушатели зарегистрированы для этого события, и их приоритеты:

1

$ php bin/console debug:event-dispatcher "Symfony\Component\Mailer\Event\FailedMessageEvent"

Отправка тестовых писем

Symfony предоставляет команду для отправки писем, которая полезна во время разработки, чтобы тестировать, правильно ли работает отправка писем:

1
2
3

# единственный обязательный аргумент - адрес получателя
# (просмотрите помощь команды, чтобы узнать о её опциях)
$ php bin/console mailer:test someone@example.com

Эта команда пропускает автобус Messenger, если он сконфигурирован, чтобы облегчить тестирование писем. даже если потребитель Messenger не работает.

Отключение доставки

Во время разработки (или тестирования), вы можете захотеть отключить доставку сообщений полностью. Вы можете сделать это, используя null://null как DSN почтовой программы, либо в ваших файлах конфигурации .env , либо в файле конфигурации почтовой программы (например, в окружениях dev или test):

1
2
3
4

# config/packages/dev/mailer.yaml
framework:
    mailer:
        dsn: 'null://null'

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

<!-- config/packages/mailer.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

    <!-- ... -->
    <framework:config>
        <framework:mailer dsn="null://null"/>
    </framework:config>
</container>

1
2
3
4
5
6
7
8

// config/packages/mailer.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework) {
    // ...
    $framework->mailer()
        ->dsn('null://null');
};

Постоянная отправка письма по одному адресу

Вместо полного отключения доставки, вы можете захотеть всегда отправлять письма по одному конкретному адресу, вместо настоящего адреса:

1
2
3
4
5

# config/packages/dev/mailer.yaml
framework:
    mailer:
        envelope:
            recipients: ['youremail@example.com']

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

<!-- config/packages/mailer.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

    <!-- ... -->
    <framework:config>
        <framework:mailer>
            <framework:envelope>
                <framework:recipient>youremail@example.com</framework:recipient>
            </framework:envelope>
        </framework:mailer>
    </framework:config>
</container>

1
2
3
4
5
6
7
8
9
10

// config/packages/mailer.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework) {
    // ...
    $framework->mailer()
        ->envelope()
            ->recipients(['youremail@example.com'])
    ;
};

Напишите функциональный тест

Чтобы функционально тестиорвать отправку письма, и даже утвердить содержание или заголовки письма, вы можете использовать встроенные утверждения:

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

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

use Symfony\Bundle\FrameworkBundle\Test\MailerAssertionsTrait;
use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;

class MailControllerTest extends WebTestCase
{
    use MailerAssertionsTrait;

    public function testMailIsSentAndContentIsOk()
    {
        $client = $this->createClient();
        $client->request('GET', '/mail/send');
        $this->assertResponseIsSuccessful();

        $this->assertEmailCount(1);

        $email = $this->getMailerMessage();

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