PHPTime

Отправка 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(), заполняет поля и отправляет сообщение.

Shell
composer require yiisoft/yii2-symfonymailer
composer check-platform-reqs

Composer подберёт зависимости с учётом ограничений проекта. Зафиксируйте 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
<?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
<?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 для этого заказа.

PHP
$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
<?php
// mail/order-paid-html.php
use yii\helpers\Html;
?>
<p>Здравствуйте, <?= Html::encode($customerName) ?>!</p>
<p>Оплата заказа №<?= Html::encode((string) $orderId) ?> получена.</p>
<p>Счёт приложен к письму.</p>
PHP
<?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. Чек-лист перед запуском

  1. Почтовый компонент подключён в веб-приложении и консоли, а требования Composer выполнены в обоих окружениях.
  2. SMTP-реквизиты доступны воркеру через окружение, а MAIL_FROM разрешён провайдером.
  3. Локальное письмо содержит ожидаемые адреса, HTML, обычный текст и нужное вложение.
  4. Тестовое письмо отправлено из рабочего окружения и получено в контрольном ящике.
  5. Временный сбой запускает ограниченный повтор, а постоянная ошибка сохраняется с понятной причиной.

Частые вопросы

Почему Yii2 сохраняет письмо в файл и не отправляет его на почту?

Проверьте useFileTransport в конфигурации, которую загрузил конкретный процесс. При значении true Yii2 сохраняет сообщение в runtime/mail. В приведённой настройке это происходит во всех окружениях с YII_ENV, отличным от prod.

Какой порт выбрать для отправки писем из Yii2?

Используйте порт и режим шифрования, указанные SMTP-провайдером. Обычно порт 587 работает с SMTP и STARTTLS, а порт 465 — с TLS с момента подключения.

Почему send() вернул true, а письмо не пришло?

В режиме SMTP успешный результат подтверждает приём сообщения сервером отправки. Проверьте журнал провайдера, возвраты, адрес получателя, папку спама и статус аутентификации домена отправителя.

Справка по теме

Ещё в разделе «Yii»

Расширения Yii 2: где искать и как устанавливать через Composer

Где искать расширения Yii 2, как проверить совместимость с PHP 8.3–8.5 и выбрать пакет. Установка через Composer, настройка и примеры популярных расширений.

7 мин

Yii 2 сегодня: установка, PHP 8.x и выбор фреймворка

Как установить Yii 2 на PHP 8.3–8.5, выбрать шаблон Basic или Advanced, проверить зависимости и решить, когда перейти на Yii 3 или Laravel.

6 мин

Миграция с Yii 1.1 на Yii 2: как перенести действующий проект

Как перенести проект с Yii 1.1 на Yii 2: пространства имён, ActiveRecord, формы, виджеты и конфигурация. План миграции с тестами и откатом.

7 мин

Как настроить автодополнение scope-методов ActiveRecord в Yii2

Настройте автодополнение scope-методов Yii2 в PhpStorm: создайте класс ActiveQuery, типизируйте find() и используйте фильтры в связях hasOne и hasMany.

7 мин