Отправка почты

Примечание: Данный раздел находится в стадии разработки.

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

Для наиболее распространённых случаев можно использовать официальное расширение yii2-swiftmailer.

Настройка

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

return [
    //....
    'components' => [
        'mailer' => [
            'class' => 'yii\swiftmailer\Mailer',
        ],
    ],
];

Основные возможности

После настройки компонента mailer, можно использовать следующий код для отправки электронного письма:

Yii::$app->mailer->compose()
    ->setFrom('from@domain.com')
    ->setTo('to@domain.com')
    ->setSubject('Message subject')
    ->setTextBody('Plain text content')
    ->setHtmlBody('<b>HTML content</b>')
    ->send();

В приведённом примере метод compose() создаёт экземпляр письма, который затем заполняется и отправляется. При необходимости можно добавить более сложную логику в этот процесс:

$message = Yii::$app->mailer->compose();
if (Yii::$app->user->isGuest) {
    $message->setFrom('from@domain.com');
} else {
    $message->setFrom(Yii::$app->user->identity->email);
}
$message->setTo(Yii::$app->params['adminEmail'])
    ->setSubject('Message subject')
    ->setTextBody('Plain text content')
    ->send();

Примечание: каждое mailer расширение состоит из 2-х основных классов: Mailer и Message. Mailer всегда знает имя класса и особенности Message. Не пытайтесь создавать экземпляр объекта Message напрямую — всегда используйте метод compose() для этого.

Также можно отправлять несколько писем сразу:

$messages = [];
foreach ($users as $user) {
    $messages[] = Yii::$app->mailer->compose()
        // ...
        ->setTo($user->email);
}
Yii::$app->mailer->sendMultiple($messages);

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

Создание содержимого письма

Yii позволяет создавать содержимое электронных писем с помощью специальных файлов представлений. По умолчанию эти файлы должны находиться по пути @app/mail.

Пример содержимого файла представления для письма:

<?php
use yii\helpers\Html;
use yii\helpers\Url;

/* @var $this \yii\web\View view component instance */
/* @var $message \yii\mail\BaseMessage instance of newly created mail message */

?>
<h2>This message allows you to visit our site home page by one click</h2>
<?= Html::a('Go to home page', Url::home('http')) ?>

Для создания содержимого письма через файл представления просто передайте имя представления методу compose().

Yii::$app->mailer->compose('home-link') // a view rendering result becomes the message body here
    ->setFrom('from@domain.com')
    ->setTo('to@domain.com')
    ->setSubject('Message subject')
    ->send();

Вы можете передать дополнительные параметры представления методу compose(), которые будут доступны внутри файлов представлений:

Yii::$app->mailer->compose('greetings', [
    'user' => Yii::$app->user->identity,
    'advertisement' => $adContent,
]);

Можно указать разные файлы представлений для HTML и простого текста:

Yii::$app->mailer->compose([
    'html' => 'contact-html',
    'text' => 'contact-text',
]);

Если вы укажете имя представления как скалярную строку, результат его рендеринга будет использоваться в качестве HTML тела, а тело простого текста будет создано путём удаления всех HTML-сущностей из HTML-версии.

Результат рендеринга представления может быть обернут в макет, который можно настроить, используя yii\mail\BaseMailer::$htmlLayout и yii\mail\BaseMailer::$textLayout. Он будет работать так же, как макеты в обычном веб-приложении. Макет можно использовать для настройки стилей CSS почты или другого общего содержимого:

<?php
use yii\helpers\Html;

/* @var $this \yii\web\View view component instance */
/* @var $message \yii\mail\MessageInterface the message being composed */
/* @var $content string main view render result */
?>
<?php $this->beginPage() ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=<?= Yii::$app->charset ?>" />
    <style type="text/css">
        .heading {...}
        .list {...}
        .footer {...}
    </style>
    <?php $this->head() ?>
</head>
<body>
    <?php $this->beginBody() ?>
    <?= $content ?>
    <div class="footer">With kind regards, <?= Yii::$app->name ?> team</div>
    <?php $this->endBody() ?>
</body>
</html>
<?php $this->endPage() ?>

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

Вы можете добавить вложение к сообщению, используя методы attach() и attachContent().

$message = Yii::$app->mailer->compose();

// attach file from local file system
$message->attach('/path/to/source/file.pdf');

// create attachment on-the-fly
$message->attachContent('Attachment content', ['fileName' => 'attach.txt', 'contentType' => 'text/plain']);

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

Вы можете вставить изображения в содержимое сообщения, используя метод embed(). Этот метод возвращает идентификатор вложения, который следует использовать в теге img. Этот метод легко использовать при создании содержимого сообщения через файл представления:

Yii::$app->mailer->compose('embed-email', ['imageFileName' => '/path/to/image.jpg'])
    // ...
    ->send();

Затем внутри файла представления вы можете использовать следующий код:

<img src="<?= $message->embed($imageFileName); ?>">

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

Разработчик часто должен проверить, какие фактические электронные письма отправляет приложение, какое у них было содержимое и т.д. Это обеспечено в Yii с помощью yii\mail\BaseMailer::useFileTransport. Если эта опция включена, она заставляет сохранять данные о письме в локальные файлы вместо обычной отправки. Эти файлы будут сохранены в yii\mail\BaseMailer::fileTransportPath, по умолчанию это @runtime/mail.

Примечание: вы можете либо сохранить сообщения в файлы, либо отправлять их реальным получателям, но не можете делать и то, и другое одновременно.

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

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

Создание собственного решения для отправки почты

Для создания собственного решения для отправки почты необходимо создать два класса: один для Mailer и другой для Message. Можно использовать yii\mail\BaseMailer и yii\mail\BaseMessage в качестве базовых классов для вашего решения. Эти классы уже содержат базовую логику, описанную в данном руководстве. Однако, их использование не является обязательным, достаточно реализовать интерфейсы yii\mail\MailerInterface и yii\mail\MessageInterface. Затем необходимо реализовать все абстрактные методы для построения вашего решения.