Отправка email-уведомлений в Yii2 через SMTP
Для отправки email в Yii2 подключите Symfony Mailer к компоненту mailer и передайте ему настройки SMTP. Разберём, как отправить уведомление о заказе, добавить две версии письма и вложение, а затем вынести отправку из HTTP-запроса в очередь.
1. Установите почтовый компонент
Для Yii2-приложения на PHP 8.3–8.5 используйте пакет yiisoft/yii2-symfonymailer. Он реализует привычный интерфейс Yii2 и передаёт отправку Symfony Mailer. Приложение по-прежнему работает через Yii::$app->mailer: вызывает compose(), заполняет поля и отправляет сообщение.
composer require yiisoft/yii2-symfonymailer
composer check-platform-reqsComposer подберёт зависимости с учётом ограничений проекта. Зафиксируйте composer.lock в репозитории и проверяйте требования платформы в том окружении, где запускается приложение. Если веб-приложение и консольный воркер используют разные образы или бинарники PHP, проверьте оба.
При переходе с Postman или обёртки над PHPMailer сохраните прикладные методы вроде sendOrderPaid() и переведите их на компонент mailer. Строковое письмо собирается через compose() и setTextBody(), а шаблонное — через compose() с именами представлений и параметрами. Пакет PHPMailer для этой схемы отдельно не нужен.
2. Настройте SMTP и локальное сохранение писем
В базовом шаблоне Yii2 вынесите конфигурацию в config/mailer.php и подключите её как значение components.mailer в веб- и консольной конфигурации. В расширенном шаблоне поместите общую настройку в common/config/main.php, а viewPath направьте на общую папку с письмами.
<?php
declare(strict_types=1);
use yii\symfonymailer\Mailer;
$config = [
'class' => Mailer::class,
'viewPath' => '@app/mail',
'htmlLayout' => false,
'textLayout' => false,
'useFileTransport' => !YII_ENV_PROD,
];
if (YII_ENV_PROD) {
$dsn = getenv('MAILER_DSN');
if ($dsn === false || trim($dsn) === '') {
throw new RuntimeException('Не задана переменная MAILER_DSN');
}
// Строку подключения передаёт окружение приложения.
$config['transport'] = ['dsn' => $dsn];
}
return $config;В MAILER_DSN задайте схему, имя пользователя, пароль, хост и порт по настройкам провайдера. Для порта 587 обычно используется smtp с повышением соединения до TLS через STARTTLS. Для порта 465 обычно используется smtps с TLS с момента подключения. Если собираете DSN из отдельных значений, пропускайте логин и пароль через rawurlencode() по отдельности. Так символы вроде @, : и # не изменят структуру строки подключения.
Передавайте DSN как секрет процесса PHP-FPM или воркера. Переменные интерактивной оболочки могут отсутствовать у обоих процессов. Проверьте также YII_ENV у консольной команды: в этом примере вне production письма сохраняются в @runtime/mail. У процесса должны быть права записи в этот каталог.
3. Отправьте первое уведомление
Для короткого уведомления достаточно текстового тела. В примере MAIL_FROM содержит адрес отправителя, разрешённый SMTP-провайдером, а адрес получателя приходит из профиля пользователя. Проверка формата помогает обнаружить ошибку данных до SMTP-вызова. Существование ящика она не подтверждает.
<?php
declare(strict_types=1);
function sendOrderPaid(string $recipient, int $orderId): void
{
$from = getenv('MAIL_FROM');
if ($from === false || filter_var($from, FILTER_VALIDATE_EMAIL) === false) {
throw new RuntimeException('Укажите допустимый адрес MAIL_FROM');
}
if (filter_var($recipient, FILTER_VALIDATE_EMAIL) === false) {
throw new InvalidArgumentException('Некорректный адрес получателя');
}
// Один заказ и один получатель на сообщение.
$sent = Yii::$app->mailer->compose()
->setFrom([$from => 'Магазин'])
->setTo($recipient)
->setSubject("Заказ №{$orderId} оплачен")
->setTextBody("Оплата заказа №{$orderId} получена.")
->send();
if (!$sent) {
throw new RuntimeException('Почтовый компонент вернул ошибку отправки');
}
}setFrom() задаёт отправителя, setReplyTo() — адрес для ответа, например ящик поддержки. Для видимой копии используйте setCc(), для скрытой — setBcc(). Персональные уведомления отправляйте отдельными сообщениями, чтобы у каждого письма были свои получатель, данные заказа и запись о попытке отправки.
4. Добавьте HTML, текстовую версию и вложение
Создайте mail/order-paid-html.php и mail/order-paid-text.php. Передайте оба имени в compose(), чтобы письмо содержало HTML и обычный текст. В примере ниже $from и $recipient уже проверены, а $invoicePath — путь к сформированному приложением PDF для этого заказа.
$message = Yii::$app->mailer->compose(
['html' => 'order-paid-html', 'text' => 'order-paid-text'],
['orderId' => $orderId, 'customerName' => $customerName],
)
->setFrom([$from => 'Магазин'])
->setTo($recipient)
->setSubject("Заказ №{$orderId} оплачен");
// Если счёт обязателен, отсутствие файла считается ошибкой.
if (!is_file($invoicePath) || !is_readable($invoicePath)) {
throw new RuntimeException('PDF счёта недоступен');
}
$message->attach($invoicePath, [
'fileName' => "invoice-{$orderId}.pdf",
'contentType' => 'application/pdf',
]);
if (!$message->send()) {
throw new RuntimeException('Не удалось отправить уведомление');
}В HTML-представлении экранируйте имя пользователя и остальные данные при выводе. Для текстового представления достаточно сформировать строки обычного текста.
<?php
// mail/order-paid-html.php
use yii\helpers\Html;
?>
<p>Здравствуйте, <?= Html::encode($customerName) ?>!</p>
<p>Оплата заказа №<?= Html::encode((string) $orderId) ?> получена.</p>
<p>Счёт приложен к письму.</p><?php
// mail/order-paid-text.php
echo "Здравствуйте, {$customerName}!\n";
echo "Оплата заказа №{$orderId} получена.\n";
echo "Счёт приложен к письму.\n";Путь к вложению определяйте по данным заказа на сервере. Учитывайте лимит провайдера на размер сообщения целиком: MIME-кодирование увеличивает размер вложения. Если письмо отправляет воркер, файл должен оставаться доступным ему и при повторной попытке.
5. Перенесите отправку в очередь
SMTP-соединение добавляет к HTTP-запросу сетевое ожидание. При оплате заказа сохраните бизнес-операцию и запись об уведомлении в одной транзакции, если потеря письма недопустима. После фиксации транзакции отдельный процесс читает эту запись или передаёт её в очередь. Такой подход закрывает окно между сохранением оплаты и постановкой задания.
- Храните в задании идентификатор уведомления. Воркер загружает адрес, параметры шаблона и вложение перед отправкой.
- Задайте уникальный ключ события, например сочетание типа уведомления, номера заказа и идентификатора получателя. Захватывайте задание атомарно, чтобы два воркера не начали отправку одновременно.
- Обрабатывайте как результат
false, так и исключения транспорта. Временные ошибки соединения и SMTP-ответы класса 4xx допускают повтор с задержкой и лимитом попыток. Ошибку авторизации, отклонённого отправителя или заведомо неверный адрес сначала нужно исправить. - Записывайте идентификатор уведомления, номер попытки и категорию ошибки. В журнале достаточно диагностики без DSN, паролей и текста письма.
Уникальный ключ защищает от повторного создания задания. При тайм-ауте после передачи письма результат может остаться неизвестным: сервер мог принять сообщение, пока воркер ждал ответ. Учитывайте возможность дубля при повторе и сверяйте такие случаи с журналом провайдера, если он доступен.
6. Проверьте отправку и доставку
Сначала откройте письмо из @runtime/mail и проверьте тему, адреса, обе версии тела и PDF. Затем отправьте тест через настоящий SMTP на контролируемый ящик из того же окружения, где будет работать воркер. Успешный send() с SMTP означает, что транспорт передал письмо серверу. Попадание во входящие проверяется отдельно.
- Ошибка соединения. Проверьте доступ к хосту и порту из контейнера или с сервера, режим TLS и доверенные сертификаты.
- Отказ в авторизации или отправке. Проверьте учётные данные, кодирование DSN и право отправлять с адреса
MAIL_FROM. - SMTP принял письмо, но получатель его не видит. Проверьте события доставки и возвраты у провайдера, папку спама и настройку SPF, DKIM и DMARC для домена отправителя.
7. Чек-лист перед запуском
- Почтовый компонент подключён в веб-приложении и консоли, а требования Composer выполнены в обоих окружениях.
- SMTP-реквизиты доступны воркеру через окружение, а
MAIL_FROMразрешён провайдером. - Локальное письмо содержит ожидаемые адреса, HTML, обычный текст и нужное вложение.
- Тестовое письмо отправлено из рабочего окружения и получено в контрольном ящике.
- Временный сбой запускает ограниченный повтор, а постоянная ошибка сохраняется с понятной причиной.
Частые вопросы
Почему Yii2 сохраняет письмо в файл и не отправляет его на почту?
Проверьте useFileTransport в конфигурации, которую загрузил конкретный процесс. При значении true Yii2 сохраняет сообщение в runtime/mail. В приведённой настройке это происходит во всех окружениях с YII_ENV, отличным от prod.
Какой порт выбрать для отправки писем из Yii2?
Используйте порт и режим шифрования, указанные SMTP-провайдером. Обычно порт 587 работает с SMTP и STARTTLS, а порт 465 — с TLS с момента подключения.
Почему send() вернул true, а письмо не пришло?
В режиме SMTP успешный результат подтверждает приём сообщения сервером отправки. Проверьте журнал провайдера, возвраты, адрес получателя, папку спама и статус аутентификации домена отправителя.