Використання вбудованого транспорту

Використання стороннього транспорту

Замість використання вашого власного SMTP-серверу або бінарності binary, ви можете відправляти листи через стороннього постачальника. Mailer підтримує декілька - встановіть той, який захочете:

Кожна бібліотека містить рецепт 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

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

1
2

# .env
MAILER_DSN=smtp://KEY:DOMAIN@smtp.eu.mailgun.org.com:25

Висока доступність

Mailer Symfony підтримує високу доступність через техніку під назвою "відмовостійкість", щоб гарантувати, що листи будуть відправлені, навіть якщо один сервер зазнає невдачі.

Транспорт failover сконфігуровано з двома або більше транспортами та ключовим словом failover:

1

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

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

Балансування навантаження

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';

Верифікація відбитку пальця TLS Peer

Додаткову верифікацію відбитків пальців можна ввімкнути за допомогою опції peer_fingerprint. Це особливо корисно, коли використовується самопідписаний сертифікат і вимкнення verify_peer є необхідним, але безпека все одно бажана. Відбиток пальця можна вказати у вигляді хешу SHA1 або MD:

1

$dsn = 'smtp://user:pass@smtp.example.com?peer_fingerprint=6A1CF3B08D175A284C30BC10DE19162307C7286E';

Disabling Automatic TLS

За замовчуванням компонент Mailer використовуватиме шифрування, якщо розширення OpenSSL увімкнено, а SMTP-сервер підтримує STARTTLS.Таку поведінку можна вимкнути за допомогою виклику setAutoTls(false) в екземплярі EsmtpTransport або встановлення опції auto_tls у значення false у DSN:

1

$dsn = 'smtp://user:pass@10.0.0.25?auto_tls=false';

Перевизначення аутентифікаторів SMTP за замовчуванням

За замовчуванням, SMTP-транспорт намагатиметься увійти в систему, використовуючи всі методи аутентифікації, доступні на SMTP-сервері, один за одним. У деяких випадках може бути корисно перевизначити підтримувані методи аутентифікації, щоб гарантувати, що бажаний метод буде використано в першу чергу.

Це можна зробити за допомогою конструктора EsmtpTransport або за допомогою методу setAuthenticators():

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;

// Обрати одну з цих 2 опцій:

// Опція 1: передати аутентифікатори конструктору
$transport = new EsmtpTransport(
    host: 'oauth-smtp.domain.tld',
    authenticators: [new XOAuth2Authenticator()]
);

// Опція 2: викликати метод для перевизначення аутентифікаторів
$transport->setAuthenticators([new XOAuth2Authenticator()]);

Інші опції

command

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

Copy

1

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

local_domain

Ім'я домену для використання в команді HELO:

Copy

1

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

restart_threshold

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

Copy

1

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

restart_threshold_sleep

Кількість секунд сну між зупинкою та перезавантаженням транспорту. Часто поєднується з restart_threshold:

Copy

1

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

ping_threshold

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

Copy

1

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

max_per_second

Кількість повідомлень, які відправляються за секунду (0, щоб відключити це обмеження)

number of messages to send per second (0 to disable this limitation):

Copy

1

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

Користувацькі фабрики транспорту

Якщо ви хочете підтримувати свою власну DSN (acme://...), ви можете створити користувацьку фабрику транспорту. Для цього створіть клас, який реалізує TransportFactoryInterface або, якщо ви бажаєте, розширте клас AbstractTransportFactory, щоб зберегти частину шаблонного коду:

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
    {
        // проаналізувати задану DSN, вилучити дані/повноваження з неї,
        // а потім створити та повернути транспорт
    }

    protected function getSupportedSchemes(): array
    {
        // це підтримує DSN, починаючи з `acme://`
        return ['acme'];
    }
}

Після створення користувацького класу транспорту, зареєструйте його як сервіс у вашому додатку і позначте його тегом mailer.transport_factory.

Адреси електронної пошти

Всі методи, які потребують адрес електронної пошти (from(), to(), та ін.), приймають як рядки, так і об'єкти адрес:

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');

        // використати масив, якщо ви хочете додати заголовок з багатьма значеннями
        // (for example in the "References" or "In-Reply-To" header)
        ->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'))
;

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

Використайте метод addPart() з BodyFile, щоб додати файли, які існують у вашій файловій системі:

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

Як варіант, ви можете прикріпляти зміст з потоку шляхом передачі його напряму DataPart :

1
2
3
4

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

Вбудовування зображень

Якщо ви хочете відобразити зображення всередині вашого листа, ви маєте їх вбудувати, а не додавати як вкладення. При використанні Twig для відображення змісту листа, як пояснюється далі в цій статті , зображення вбудовуються автоматично. В іншому випадку, вам потрібно буде вбудувати їх вручну.

Спочатку, використайте метод addPart(), щоб додати зображення з файлу або потоку:

1
2
3
4
5
6
7

$email = (new Email())
    // ...
    // отримати зміст збораження з PHP-джерела
    ->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())
;

Використайте метод 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> ...')
;

Ви також можете використовувати метод DataPart::setContentId()

для визначення користувацького Content-ID для зображення і використання його як посилання на cid:

Copy

1
2
3
4
5
6
7
8

$part = new DataPart(new File('/path/to/images/signature.gif'));
$part->setContentId('footer-signature');

$email = (new Email())
    // ...
    ->addPart($part->asInline())
    ->html('... <img src="cid:footer-signature"> ...')
;

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

    // передайте змінні (ім'я => значення) шаблону
    ->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-зміст у текст.

Symfony використовує наступну стратегію коли генерує текстову версію листа:

• Якщо було сконфігуровано чіткий перетворювач з HTML на текст (див. twig.mailer.html_to_text_converter ), вона викликає його;
• Якщо ні, і у вас встановлено 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): void {
    // ...

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

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

1
2
3
4
5

{# '@images/' відноситься до простору імен Twig, визначеного раніше #}
<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): void {
    // ...

    // вкажіть туди, де живуть ваші 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
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;
    }
    // зробити щось з повідомленням (логування, ...)

    // та/або додати якісь штампи Мессенджеру
    $event->addStamp(new SomeMessengerStamp());
}

Якщо ви хочете запобігти відправці повідомлення, викличте reject() (це також зупинить розповсюдження події):

1
2
3
4
5
6

use Symfony\Component\Mailer\Event\MessageEvent;

public function onMessage(MessageEvent $event): void
{
    $event->reject();
}

Виконайте цю команду, щоб дізнатися, які слухачі зареєстровані для цієї події, та їх пріоритети:

1

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

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"

Підключення Email Catcher

При локальній розробці рекомендовано використовувати email catcher. Якщо ви включили підтримку Docker через рецепти Symfony, email catcher конфігурується автоматично. На додаток, якщо ви використовуєте локальний веб-сервер Symfony, mailer DSN автоматично розкриваєтьсся через бінарну інтеграцію symfony з Docker.

Відправка тестових електронних листів

Symfony надає команду для відправки листів, яка корисна під час розробки, щоб тестувати, чи правильно працює відправка електронних листів:

1
2
3

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

Ця команда обходить автобус Messenger, якщо його сконфігуровано, щоб полегшити тестування листів, навіть якщо споживач Messenger не працює.

Відключення доставки

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

1
2
3
4
5

# config/packages/mailer.yaml
when@dev:
    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): void {
    // ...
    $framework->mailer()
        ->dsn('null://null');
};

Постійна відправка листа за однією адресою

Замість повного відключення доставки, ви можете захотіти завжди відправляти листи за однією конкретною адресою, замість справжньої адреси:

1
2
3
4
5
6

# config/packages/mailer.yaml
when@dev:
    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): void {
    // ...
    $framework->mailer()
        ->envelope()
            ->recipients(['youremail@example.com'])
    ;
};

Використовуйте опцію allowed_recipients, щоб вказати винятки з поведінки, визначеної в опції recipients; дозволяючи листам, спрямованим до цих конкретних одержувачів, зберігати свою початкову адресу:

1
2
3
4
5
6
7
8
9
10

# config/packages/mailer.yaml
when@dev:
    framework:
        mailer:
            envelope:
                recipients: ['youremail@example.com']
                allowed_recipients:
                    - 'internal@example.com'
                    # ви також можете використати регулярний вираз для визначення дозволених отримувачів
                    - 'internal-.*@example.(com|fr)'

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

<!-- 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:allowed-recipient>internal@example.com</framework:allowed-recipient>
                <!-- ви також можете використати регулярний вираз для визначення дозволених отримувачів -->
                <framework:allowed-recipient>internal-.*@example.(com|fr)</framework:allowed-recipient>
            </framework:envelope>
        </framework:mailer>
    </framework:config>
</container>

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

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

return static function (FrameworkConfig $framework): void {
    // ...
    $framework->mailer()
        ->envelope()
            ->recipients(['youremail@example.com'])
            ->allowedRecipients([
                'internal@example.com',
                // ви також можете використати регулярний вираз для визначення дозволених отримувачів
                'internal-.*@example.(com|fr)',
            ])
    ;
};

З цією конфігурацією всі листи будуть надсилатися на youremail@example.com, окрім тих, що надсилаються на internal@example.com, internal-monitoring@example.fr і т.д., які будуть отримувати листи як зазвичай.

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

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

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