Отправка почты из Yii 2: пошаговая инструкция

К концу этой инструкции вы отправите первое письмо из приложения на Yii 2 через SMTP-сервер и проверите, что оно дошло. Разберём три вещи: настройку компонента mailer, отправку простого письма из кода и подключение HTML-шаблона. На всё уйдёт минут двадцать, если у вас уже есть данные для доступа к почтовому серверу.

Инструкция написана для Yii 2 (2.0.x) с расширением yiisoft/yii2-swiftmailer — оно входит в стандартные шаблоны basic и advanced. В Yii 3 механизм другой, здесь его не касаемся.

Что нужно иметь до начала

Проверьте это заранее, чтобы не упереться на середине:

• установленное приложение на Yii 2 (шаблон basic или advanced) и доступ к терминалу в корне проекта;
• PHP 7.x или новее с включённым Composer;
• данные SMTP: хост, порт, логин, пароль и тип шифрования. Их даёт ваш почтовый провайдер — Яндекс 360, Mail.ru для бизнеса, Gmail, собственный сервер или транзакционный сервис вроде SendGrid;
• доступ на запись в каталог runtime/ — туда пишутся письма при отладке.

Если расширения swiftmailer нет, установите его из корня проекта:

composer require yiisoft/yii2-swiftmailer

Проверка: в файле composer.json в блоке require появится строка с yiisoft/yii2-swiftmailer, а в каталоге vendor/yiisoft/ — папка расширения.

Не вписывайте пароль от почты прямо в конфиг, который лежит в Git. Пароль SMTP — это ключ ко всей вашей рассылке. Выносите его в переменную окружения или в незакоммиченный локальный файл конфигурации.

Шаг 1. Настроить компонент mailer

Компонент mailer описывается в секции components конфигурационного файла. В шаблоне basic это config/web.php, в advanced — common/config/main.php. Найдите массив components и приведите блок mailer к такому виду:

'mailer' => [
    'class' => 'yii\swiftmailer\Mailer',
    // на боевом сервере поставьте false, чтобы письма реально уходили
    'useFileTransport' => false,
    'transport' => [
        'class' => 'Swift_SmtpTransport',
        'host' => 'smtp.example.com',
        'username' => 'noreply@example.com',
        'password' => getenv('SMTP_PASSWORD'), // пароль из переменной окружения
        'port' => 465,
        'encryption' => 'ssl',
    ],
],

Порт и тип шифрования зависят от провайдера: чаще всего это 465 с ssl или 587 с tls. Точные значения смотрите в справке своего почтового сервиса — угадывать не стоит, письмо просто не уйдёт.

Проверка: откройте приложение в браузере. Если конфиг с синтаксической ошибкой, Yii покажет исключение с указанием файла и строки. Пустой экран без ошибок — значит, конфиг разобрался.

Режим отладки: письма в файлы

Пока вы не уверены в SMTP-доступе, включите 'useFileTransport' => true. Тогда Yii не будет никуда ничего отправлять, а сложит письма в runtime/mail/ в виде .eml-файлов. Их можно открыть текстовым редактором и увидеть заголовки, тему и тело — удобно, чтобы проверить шаблон до реальной отправки.

Шаг 2. Отправить первое письмо

Отправка идёт через компонент Yii::$app->mailer. Простейший вариант с текстовым телом — например, в любом действии контроллера:

use Yii;

$sent = Yii::$app->mailer->compose()
    ->setFrom('noreply@example.com')
    ->setTo('client@example.com')
    ->setSubject('Проверка отправки')
    ->setTextBody('Это тестовое письмо из Yii 2.')
    ->send();

if ($sent) {
    echo 'Письмо отправлено';
} else {
    echo 'Отправка не удалась';
}

Метод send() возвращает true, если письмо принято транспортом, и false, если нет. Адрес в setFrom() должен совпадать с тем ящиком, под которым вы авторизуетесь на SMTP, иначе провайдеры часто отклоняют письмо.

Проверка: при useFileTransport => true в runtime/mail/ появится новый .eml-файл. При false — письмо придёт на указанный в setTo() адрес (загляните и в папку «Спам»).

Шаг 3. Подключить HTML-шаблон

Текстовые письма годятся для теста, но клиенту обычно нужно вёрстку. В Yii шаблоны писем лежат в каталоге mail/ (в basic) или common/mail/ (в advanced). Создайте файл mail/welcome.php:

<?php
/* @var $this yii\web\View */
/* @var $name string */
?>
<h2>Здравствуйте, <?= yii\helpers\Html::encode($name) ?></h2>
<p>Спасибо за регистрацию.</p>

Теперь передайте имя шаблона первым аргументом в compose() и данные для него — вторым:

Yii::$app->mailer->compose('welcome', ['name' => 'Анна'])
    ->setFrom('noreply@example.com')
    ->setTo('anna@example.com')
    ->setSubject('Добро пожаловать')
    ->send();

Yii отрендерит файл welcome.php и подставит результат как HTML-тело письма. Обратите внимание на Html::encode() вокруг пользовательских данных — без этого в письмо можно случайно протащить постороннюю разметку.

Проверка: в полученном письме имя подставилось, а не осталось строкой <?= $name ?>. Если видите PHP-код как текст — шаблон не отрендерился, проверьте путь и имя файла.

HTML и текст одновременно

Чтобы почтовики без поддержки HTML тоже показали письмо, задайте два шаблона через массив с ключами html и text:

Yii::$app->mailer->compose(
    ['html' => 'welcome-html', 'text' => 'welcome-text'],
    ['name' => 'Анна']
);

Если не получилось

Пять типичных ошибок и что с ними делать:

• Connection could not be established with host smtp.example.com — неверный хост или порт, либо сервер недоступен из вашей сети. Сверьте хост и порт со справкой провайдера, проверьте, что исходящие соединения на этот порт не закрыты файрволом или хостингом.
• Expected response code 235 but got code 535 — сервер отклонил авторизацию. Неверный логин или пароль. У Gmail и Яндекса для сторонних приложений часто нужен отдельный пароль приложения, а не основной пароль от аккаунта.
• Письмо уходит (send() вернул true), но не приходит — смотрите в «Спам». Причина обычно в отсутствии SPF/DKIM-записей у домена отправителя или в том, что адрес From не совпадает с ящиком авторизации.
• Class 'Swift_SmtpTransport' not found — не установлено расширение swiftmailer. Вернитесь к шагу с composer require.
• Письма всегда падают в runtime/mail/ и не уходят — у вас включён useFileTransport => true. Для боевой отправки поставьте false.

Что делать дальше

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

• вынесите SMTP-пароль из конфига в переменную окружения или в config/params-local.php (в advanced), который не попадает в Git;
• для массовых или отложенных рассылок не отправляйте письма прямо в HTTP-запросе — ставьте задачу в очередь (например, через yii2-queue), иначе страница будет висеть на время соединения с SMTP;
• настройте на домене SPF и DKIM, чтобы письма не уходили в спам — это делается на стороне DNS и почтового провайдера, а не в коде Yii;
• для транзакционных писем в объёме присмотритесь к специализированным сервисам с API и отчётами о доставке.

Настройка вложений и встроенных изображений — отдельная тема, здесь мы её не разбирали.