git 107f4bc901540cc7199e3fa055a73ad854324866
- Введение
- Генерация отправлений
- Написание отправлений
- Отправления с разметкой Markdown
- Отправка почты
- Отображение отправлений
- Локализация отправлений
- Тестирование отправлений
- Почта и локальная разработка
- События
Отправка электронной почты не должна быть сложной. Laravel предлагает чистый и простой почтовый API на базе популярной библиотеки SwiftMailer. Laravel и SwiftMailer обеспечены драйверами для отправки электронной почты через SMTP, Mailgun, Postmark, Amazon SES и sendmail, что позволяет быстро начать отправку почты через локальный или облачный сервис по вашему выбору.
Почтовые службы Laravel могут быть настроены через конфигурационный файл config/mail.php вашего приложения. Каждая почтовая программа, настроенная в этом файле, может иметь свою собственную уникальную конфигурацию и даже свой собственный уникальный «транспорт», что позволяет вашему приложению использовать различные почтовые службы для отправки определенных сообщений электронной почты. Например, ваше приложение может использовать Postmark для отправки транзакционных писем, а Amazon SES – для массовых рассылок.
В конфигурационном файле config/mail.php вы найдете массив mailers. Этот массив содержит образец записи конфигурации для каждого из основных почтовых драйверов / транспортов, поддерживаемых Laravel, в то время как значение конфигурации default определяет, какая почтовая программа будет использоваться по умолчанию, когда ваше приложение должно отправить сообщение электронной почты.
Драйверы на основе API, такие, как Mailgun и Postmark, часто проще в использовании и быстрее, чем отправка почты через SMTP-серверы. По возможности мы рекомендуем использовать один из этих драйверов. Для всех драйверов на основе API требуется HTTP-библиотека Guzzle, которую можно установить через менеджер пакетов Composer:
composer require guzzlehttp/guzzle
Чтобы использовать драйвер Mailgun, сначала установите HTTP-библиотеку Guzzle. Затем установите параметру default в вашем конфигурационном файле config/mail.php значение mailgun. Затем убедитесь, что ваш конфигурационный файл config/services.php содержит следующие параметры:
'mailgun' => [
'domain' => env('MAILGUN_DOMAIN'),
'secret' => env('MAILGUN_SECRET'),
],
Если вы не используете регион Mailgun США, то вы можете определить конечную точку своего региона в конфигурации файла services:
'mailgun' => [
'domain' => env('MAILGUN_DOMAIN'),
'secret' => env('MAILGUN_SECRET'),
'endpoint' => env('MAILGUN_ENDPOINT', 'api.eu.mailgun.net'),
],
Чтобы использовать драйвер Postmark, установите транспорт SwiftMailer для Postmark через Composer:
composer require wildbit/swiftmailer-postmark
Затем установите HTTP-библиотеку Guzzle и установите для параметра default в конфигурационном файле config/mail.php значение postmark. Наконец, убедитесь, что ваш конфигурационный файл config/services.php содержит следующие параметры:
'postmark' => [
'token' => env('POSTMARK_TOKEN'),
],
Если вы хотите указать поток сообщений Postmark, который должен использоваться данной почтовой программой, вы можете добавить параметр конфигурации message_stream_id в массив конфигурации почтовой программы. Этот массив конфигурации можно найти в файле конфигурации вашего приложения config/mail.php:
'postmark' => [
'transport' => 'postmark',
'message_stream_id' => env('POSTMARK_MESSAGE_STREAM_ID'),
],
Таким образом, вы также можете настроить несколько почтовых программ Postmark с разными потоками сообщений.
Чтобы использовать драйвер Amazon SES, сначала необходимо установить Amazon AWS SDK для PHP. Вы можете установить эту библиотеку через менеджер пакетов Composer:
composer require aws/aws-sdk-phpЗатем установите для параметра default в вашем файле конфигурации config/mail.php значение ses и убедитесь, что конфигурационный файл config/services.php содержит следующие параметры:
'ses' => [
'key' => env('AWS_ACCESS_KEY_ID'),
'secret' => env('AWS_SECRET_ACCESS_KEY'),
'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
],
Чтобы использовать AWS временные учетные данные через токен сеанса, вы можете добавить ключ token в конфигурацию SES вашего приложения:
'ses' => [
'key' => env('AWS_ACCESS_KEY_ID'),
'secret' => env('AWS_SECRET_ACCESS_KEY'),
'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
'token' => env('AWS_SESSION_TOKEN'),
],
Если вы хотите определить дополнительные параметры, которые Laravel должен передать методу SendRawEmail AWS SDK при отправке сообщения электронной почты, вы можете определить массив options в конфигурации ses:
'ses' => [
'key' => env('AWS_ACCESS_KEY_ID'),
'secret' => env('AWS_SECRET_ACCESS_KEY'),
'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
'options' => [
'ConfigurationSetName' => 'MyConfigurationSet',
'Tags' => [
['Name' => 'foo', 'Value' => 'bar'],
],
],
],
Иногда внешняя служба, которую вы настроили для отправки почты вашего приложения, может не работать. В этих случаях может быть полезно определить одну или несколько резервных конфигураций доставки почты, которые будут использоваться в случае, если ваш основной драйвер доставки не работает.
Для этого вы должны определить почтовую программу в файле конфигурации вашего приложения mail, который использует транспортfailover. Массив конфигурации для почтовой программы failover вашего приложения должен содержать массив mailers, который определяет очередность, в котором почтовые драйверы должны быть выбраны для доставки:
'mailers' => [
'failover' => [
'transport' => 'failover',
'mailers' => [
'postmark',
'mailgun',
'sendmail',
],
],
// ...
],
После того как ваш почтовый агент аварийного переключения был определен, вы должны установить его как почтовую программу по умолчанию, используемую вашим приложением, указав ее имя как значение конфигурационного ключа default в файле конфигурации вашего приложения mail:
'default' => env('MAIL_MAILER', 'failover'),
При создании приложений Laravel каждый тип электронной почты, отправляемой вашим приложением, представляется экземпляром класса Illuminate\Mail\Mailable. Эти классы хранятся в каталоге app/Mail. Не беспокойтесь, если вы не видите этот каталог в своем приложении, поскольку он будет сгенерирован для вас, когда вы создадите свой первый почтовый класс с помощью команды make:mail Artisan:
php artisan make:mail OrderShipped
После того как вы создали почтовый класс, откройте его, чтобы мы могли изучить его содержимое. Во-первых, обратите внимание, что вся конфигурация почтового класса выполняется в методе build. В этом методе вы можете вызывать различные методы, такие как from, subject, view, и attach, для настройки представления и доставки электронного письма.
{tip} Вы можете указывать зависимости от метода почтового сообщения
build. Сервис-контейнер Laravel автоматически внедряет эти зависимости.
Во-первых, давайте рассмотрим настройку отправителя электронного письма. Или, другими словами, от кого будет электронное письмо. Настроить отправителя можно двумя способами. Во-первых, вы можете использовать метод from в методе build вашего почтового класса:
/**
* Создать сообщение.
*
* @return $this
*/
public function build()
{
return $this->from('[email protected]', 'Example')
->view('emails.orders.shipped');
}
Однако, если ваше приложение использует один и тот же адрес from для всех своих электронных писем, вызов метода from в каждом создаваемом вами классе рассылки может стать громоздким. Вместо этого вы можете указать глобальный адрес отправителя в файле конфигурации config/mail.php. Этот адрес будет использоваться, если в почтовом классе не указан другой адрес в методе from:
'from' => ['address' => '[email protected]', 'name' => 'App Name'],
Кроме того, вы можете определить глобальный адрес reply_to в конфигурационном файле config/mail.php:
'reply_to' => ['address' => '[email protected]', 'name' => 'App Name'],
Внутри метода build почтового класса вы можете использовать метод view, чтобы указать, какой шаблон следует использовать при отображении содержимого электронного письма. Поскольку каждое электронное письмо для визуализации своего содержимого обычно использует шаблон Blade, вы получаете всю мощь и удобство механизма шаблонов Blade при создании HTML-кода электронной почты:
/**
* Создать сообщение.
*
* @return $this
*/
public function build()
{
return $this->view('emails.orders.shipped');
}
{tip} Вы можете создать каталог
resources/views/emailsдля размещения всех ваших шаблонов электронной почты; однако, вы можете размещать их где угодно в каталогеresources/views.
Если вы хотите определить текстовую версию вашего электронного письма, то вы можете использовать метод text. Как и метод view, метод text принимает имя шаблона, которое будет использоваться для отображения содержимого электронного письма. Вы можете определить как HTML, так и текстовую версию вашего сообщения:
/**
* Создать сообщение.
*
* @return $this
*/
public function build()
{
return $this->view('emails.orders.shipped')
->text('emails.orders.shipped_plain');
}
Как правило, вам нужно передать в шаблон некоторые данные, которые можно использовать при отображении HTML-кода электронного письма. Есть два способа сделать данные доступными для вашего шаблона. Во-первых, любое публичное свойство, определенное в вашем почтовом классе, будет автоматически доступно для шаблона. Так, например, можно передать данные в конструктор почтового класса и присвоить этим данные публичным свойствам, определенным в классе:
<?php
namespace App\Mail;
use App\Models\Order;
use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Queue\SerializesModels;
class OrderShipped extends Mailable
{
use Queueable, SerializesModels;
/**
* Экземпляр заказа.
*
* @var \App\Models\Order
*/
public $order;
/**
* Создать экземпляр нового сообщения.
*
* @param \App\Models\Order $order
* @return void
*/
public function __construct(Order $order)
{
$this->order = $order;
}
/**
* Создать сообщение.
*
* @return $this
*/
public function build()
{
return $this->view('emails.orders.shipped');
}
}
После того как данные были заданы как публичные свойства, они будут автоматически доступны в вашем шаблоне, поэтому вы можете получить к ним доступ так же, как и к любым другим данным в ваших шаблонах Blade:
<div>
Price: {{ $order->price }}
</div>
Если вы хотите настроить формат данных вашего электронного письма перед их отправкой в шаблон, то вы можете вручную передать свои данные в шаблон с помощью метода with. Как правило, вы по-прежнему будете передавать данные через конструктор почтового класса; однако, вы должны установить для этих данных свойства protected или private, чтобы данные не были автоматически доступны для шаблона. Затем при вызове метода with передайте массив, доступных для шаблона данных:
<?php
namespace App\Mail;
use App\Models\Order;
use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Queue\SerializesModels;
class OrderShipped extends Mailable
{
use Queueable, SerializesModels;
/**
* Экземпляр заказа.
*
* @var \App\Models\Order
*/
protected $order;
/**
* Создать экземпляр нового сообщения.
*
* @param \App\Models\Order $order
* @return void
*/
public function __construct(Order $order)
{
$this->order = $order;
}
/**
* Создать сообщение.
*
* @return $this
*/
public function build()
{
return $this->view('emails.orders.shipped')
->with([
'orderName' => $this->order->name,
'orderPrice' => $this->order->price,
]);
}
}
После того как данные были переданы методу with, они автоматически станут доступны в вашем шаблоне, поэтому вы можете получить к ним доступ так же, как и к любым другим данным в ваших шаблонах Blade:
<div>
Price: {{ $orderPrice }}
</div>
Чтобы добавить вложения к электронному письму, используйте метод attach в методе build почтового класса. Метод attach принимает полный путь к файлу в качестве своего первого аргумента:
/**
* Создать сообщение.
*
* @return $this
*/
public function build()
{
return $this->view('emails.orders.shipped')
->attach('/path/to/file');
}
При прикреплении файлов к сообщению вы также можете указать отображаемое имя и / или MIME-тип, передав массив в качестве второго аргумента методу attach:
/**
* Создать сообщение.
*
* @return $this
*/
public function build()
{
return $this->view('emails.orders.shipped')
->attach('/path/to/file', [
'as' => 'name.pdf',
'mime' => 'application/pdf',
]);
}
Если вы сохранили файл на одном из дисков файлового хранилища, то вы можете прикрепить его к электронному письму с помощью метода attachFromStorage:
/**
* Создать сообщение.
*
* @return $this
*/
public function build()
{
return $this->view('emails.orders.shipped')
->attachFromStorage('/path/to/file');
}
При необходимости вы можете указать имя прикрепленного файла и дополнительные параметры, используя второй и третий аргументы метода attachFromStorage:
/**
* Создать сообщение.
*
* @return $this
*/
public function build()
{
return $this->view('emails.orders.shipped')
->attachFromStorage('/path/to/file', 'name.pdf', [
'mime' => 'application/pdf'
]);
}
Метод attachFromStorageDisk используется, если вам нужно указать диск хранения, отличный от вашего диска по умолчанию:
/**
* Создать сообщение.
*
* @return $this
*/
public function build()
{
return $this->view('emails.orders.shipped')
->attachFromStorageDisk('s3', '/path/to/file');
}
Метод attachData используется для присоединения необработанной строки в качестве вложения. Например, вы можете использовать этот метод, если вы создали PDF-файл в памяти и хотите прикрепить его к электронному письму, не записывая его на диск. Метод attachData принимает байты необработанных данных в качестве первого аргумента, имя файла в качестве второго аргумента и массив параметров в качестве третьего аргумента:
/**
* Создать сообщение.
*
* @return $this
*/
public function build()
{
return $this->view('emails.orders.shipped')
->attachData($this->pdf, 'name.pdf', [
'mime' => 'application/pdf',
]);
}
Встраивание изображений в ваши электронные письма, как правило, обременительно; однако Laravel предлагает удобный способ прикреплять изображения к вашим письмам. Чтобы встроить изображение, используйте метод embed для переменной $message в вашем шаблоне электронной почты. Laravel автоматически делает переменную $message доступной для всех ваших шаблонов электронной почты, поэтому вам не нужно беспокоиться о ее передаче вручную:
<body>
Here is an image:
<img src="{{ $message->embed($pathToImage) }}">
</body>
{note} Переменная
$messageнедоступна в шаблонах текстовых сообщений, так как в текстовых сообщениях не используются встроенные вложения.
Если у вас уже есть строка необработанных данных изображения, которую вы хотите встроить в шаблон электронной почты, то вы можете вызвать метод embedData для переменной $message. При вызове метода embedData вам необходимо указать имя файла, которое должно быть присвоено встраиваемому изображению:
<body>
Here is an image from raw data:
<img src="{{ $message->embedData($data, 'example-image.jpg') }}">
</body>
Метод withSwiftMessage базового класса Mailable позволяет вам зарегистрировать замыкание, которое будет вызываться с экземпляром сообщения SwiftMailer перед отправкой сообщения. Это дает вам возможность глубокой настройки сообщения перед его доставкой:
/**
* Создать сообщение.
*
* @return $this
*/
public function build()
{
$this->view('emails.orders.shipped');
$this->withSwiftMessage(function ($message) {
$message->getHeaders()->addTextHeader(
'Custom-Header', 'Header Value'
);
});
return $this;
}
Почтовые сообщения с разметкой Markdown позволяют вам воспользоваться преимуществами предварительно созданных шаблонов и компонентов почтовых уведомлений в ваших почтовых рассылках. Поскольку сообщения написаны на Markdown, Laravel может отображать красивые, отзывчивые HTML-шаблоны для сообщений, а также автоматически генерировать их аналоги в виде простого текста.
Чтобы сгенерировать почтовый класс с соответствующим шаблоном Markdown, вы можете использовать параметр --markdown в команде make:mail Artisan:
php artisan make:mail OrderShipped --markdown=emails.orders.shipped
Затем в методе build почтового класса вызовите метод markdown вместо метода view. Метод markdown принимает имя шаблона Markdown и необязательный массив данных, которые должны быть доступны для шаблона:
/**
* Создать сообщение.
*
* @return $this
*/
public function build()
{
return $this->from('[email protected]')
->markdown('emails.orders.shipped', [
'url' => $this->orderUrl,
]);
}
Почтовые сообщения Markdown используют комбинацию компонентов Blade и синтаксиса Markdown, которые позволяют легко создавать почтовые сообщения, используя предварительно созданные компоненты пользовательского интерфейса электронной почты Laravel:
@component('mail::message')
# Order Shipped
Your order has been shipped!
@component('mail::button', ['url' => $url])
View Order
@endcomponent
Thanks,<br>
{{ config('app.name') }}
@endcomponent
{tip} Не используйте лишние отступы при написании писем Markdown. По стандартам Markdown парсеры будут отображать контент с отступом в виде блоков кода.
Компонент кнопки отображает ссылку на кнопку по центру. Компонент принимает два аргумента: url и необязательный color. Поддерживаемые цвета: primary, success, и error. Вы можете добавить к сообщению столько компонентов кнопки, сколько захотите:
@component('mail::button', ['url' => $url, 'color' => 'success'])
View Order
@endcomponent
Компонент панели отображает указанный блок текста на панели, цвет фона которой немного отличается от цвета остальной части сообщения. Это позволяет привлечь внимание к указанному блоку текста:
@component('mail::panel')
This is the panel content.
@endcomponent
Компонент таблицы позволяет преобразовать таблицу Markdown в таблицу HTML. Компонент принимает в качестве содержимого таблицу Markdown. Выравнивание столбцов таблицы поддерживается с использованием синтаксиса выравнивания таблицы Markdown по умолчанию:
@component('mail::table')
| Laravel | Table | Example |
| ------------- |:-------------:| --------:|
| Col 2 is | Centered | $10 |
| Col 3 is | Right-Aligned | $20 |
@endcomponent
Вы можете экспортировать все почтовые компоненты Markdown в собственное приложение для настройки. Чтобы экспортировать компоненты, используйте команду vendor:publish Artisan с параметром --tag=laravel-mail:
php artisan vendor:publish --tag=laravel-mail
Эта команда опубликует почтовые компоненты Markdown в каталоге resources/views/vendor/mail. Каталог mail будет содержать каталог html и text, каждый из которых содержит соответствующие представления каждого доступного компонента. Вы можете настроить эти компоненты по своему усмотрению.
После экспорта компонентов в каталоге resources/views/vendor/mail/html/themes будет содержаться файл default.css. Вы можете отредактировать CSS в этом файле, и ваши стили будут автоматически преобразованы во встроенные стили CSS в HTML-представлениях ваших почтовых сообщений Markdown.
Если вы хотите создать совершенно новую тему для компонентов Laravel Markdown, вы можете поместить файл CSS в каталог html/themes. После присвоения имени и сохранения файла CSS обновите параметр theme в файле конфигурации вашего приложения config/mail.php, чтобы он соответствовал имени вашей новой темы.
Чтобы настроить тему для отдельного почтового сообщения, вы можете установить в свойстве $theme почтового класса имя темы, которое следует использовать при отправке этого почтового сообщения.
Чтобы отправить сообщение, используйте метод to фасада Mail. Метод to принимает адрес электронной почты, экземпляр пользователя или коллекцию пользователей. Если вы передаете объект или коллекцию объектов, почтовая программа будет автоматически использовать их свойства email и name при определении получателей электронной почты, поэтому убедитесь, что эти атрибуты доступны для ваших объектов. После того как вы указали своих получателей, вы можете передать экземпляр вашего почтового класса методу send:
<?php
namespace App\Http\Controllers;
use App\Http\Controllers\Controller;
use App\Mail\OrderShipped;
use App\Models\Order;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Mail;
class OrderShipmentController extends Controller
{
/**
* Отправить заказ.
*
* @param \Illuminate\Http\Request $request
* @return \Illuminate\Http\Response
*/
public function store(Request $request)
{
$order = Order::findOrFail($request->order_id);
// Отправляем заказ ...
Mail::to($request->user())->send(new OrderShipped($order));
}
}
Вы не ограничены простым указанием получателей при отправке сообщения. Вы можете указать получателей to, cc и bcc, связав их соответствующие методы вместе:
Mail::to($request->user())
->cc($moreUsers)
->bcc($evenMoreUsers)
->send(new OrderShipped($order));
Иногда требуется отправить почтовое сообщение списку получателей, перебирая массив получателей / адресов электронной почты. Однако, поскольку метод to добавляет адреса электронной почты к списку получателей почтового сообщения, каждая итерация цикла будет отправлять другое электронное письмо каждому предыдущему получателю. Следовательно, вы всегда должны повторно создавать почтовый экземпляр для каждого получателя:
foreach (['[email protected]', '[email protected]'] as $recipient) {
Mail::to($recipient)->send(new OrderShipped($order));
}
По умолчанию Laravel будет отправлять электронную почту, используя почтовую программу, настроенную как почтовую программу default в файле конфигурации вашего приложения mail. Однако вы можете использовать метод mailer для отправки сообщения с использованием определенной конфигурации почтовой программы:
Mail::mailer('postmark')
->to($request->user())
->send(new OrderShipped($order));
Поскольку отправка сообщений электронной почты может негативно повлиять на время отклика вашего приложения, многие разработчики ставят сообщения электронной почты в очередь для фоновой отправки. Laravel упрощает это с помощью встроенного API унифицированной очереди. Чтобы поставить почтовое сообщение в очередь, используйте метод queue фасада Mail после указания получателей сообщения:
Mail::to($request->user())
->cc($moreUsers)
->bcc($evenMoreUsers)
->queue(new OrderShipped($order));
Этот метод автоматически помещает задание в очередь, чтобы сообщение отправлялось в фоновом режиме. Перед использованием этого функционала вам необходимо настроить очереди.
Если вы хотите отложить доставку электронного сообщения в очереди, вы можете использовать метод later. В качестве первого аргумента метод later принимает экземпляр DateTime, указывающий, когда сообщение должно быть отправлено:
Mail::to($request->user())
->cc($moreUsers)
->bcc($evenMoreUsers)
->later(now()->addMinutes(10), new OrderShipped($order));
Поскольку все почтовые классы, сгенерированные с помощью команды make:mail, используют трейт Illuminate\Bus\Queueable, вы можете вызвать методы onQueue и onConnection для любого экземпляра почтового класса, что позволит вам указать соединение и имя очереди для сообщения:
$message = (new OrderShipped($order))
->onConnection('sqs')
->onQueue('emails');
Mail::to($request->user())
->cc($moreUsers)
->bcc($evenMoreUsers)
->queue($message);
Если у вас есть почтовые классы, которые вы хотите всегда ставить в очередь, то вы можете реализовать контракт ShouldQueue для этого класса. Теперь, даже если вы вызовете метод send для отправки, почтовый класс все равно будет помещен в очередь, поскольку он содержит контракт:
use Illuminate\Contracts\Queue\ShouldQueue;
class OrderShipped extends Mailable implements ShouldQueue
{
//
}
Когда помещенные в очередь почтовые сообщения отправляются в рамках транзакций базы данных, они могут быть обработаны очередью до того, как транзакция базы данных будет зафиксирована. Когда это происходит, любые обновления, внесенные вами в модели или записи базы данных во время транзакции базы данных, могут еще не быть отражены в базе данных. Кроме того, любые модели или записи базы данных, созданные в рамках транзакции, могут не существовать в базе данных. Если ваше почтовое сообщение зависит от этих моделей, при обработке задания, отправляющего почтовое сообщение в очереди, могут возникнуть непредвиденные ошибки.
Если для параметра after_commit конфигурации вашего соединения с очередью задано значение false, то вы все равно можете указать, что конкретное почтовое сообщение в очереди должно быть отправлено после того, как все открытые транзакции базы данных были зафиксированы, путем вызова метода afterCommit при отправке почтового сообщения:
Mail::to($request->user())->send(
(new OrderShipped($order))->afterCommit()
);
В качестве альтернативы вы можете вызвать метод afterCommit из конструктора вашего почтового сообщения:
<?php
namespace App\Mail;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Mail\Mailable;
use Illuminate\Queue\SerializesModels;
class OrderShipped extends Mailable implements ShouldQueue
{
use Queueable, SerializesModels;
/**
* Create a new message instance.
*
* @return void
*/
public function __construct()
{
$this->afterCommit();
}
}
{tip} Чтобы больше узнать о том, как обойти эти проблемы, просмотрите документацию, касающуюся заданий в очереди и транзакций базы данных.
Иногда требуется получить HTML-содержимое почтового сообщения, не отправляя его. Для этого вы можете вызвать метод render почтового сообщения. Этот метод вернет проанализированное HTML-содержимое почтового сообщения в виде строки:
use App\Mail\InvoicePaid;
use App\Models\Invoice;
$invoice = Invoice::find(1);
return (new InvoicePaid($invoice))->render();
При разработке шаблона почтового сообщения удобно быстро просмотреть визуализированное почтовое сообщение в браузере как типичный шаблон Blade. По этой причине Laravel позволяет вам возвращать любое почтовое сообщение непосредственно из замыкания маршрута или контроллера. Когда почтовое сообщение возвратится, оно будет обработано и отображено в браузере, что позволит вам быстро просмотреть его дизайн без необходимости отправлять его на реальный адрес электронной почты:
Route::get('/mailable', function () {
$invoice = App\Models\Invoice::find(1);
return new App\Mail\InvoicePaid($invoice);
});
{note} Встраиваемые вложения не будут отображаться при предварительном просмотре почтового сообщения в вашем браузере. Чтобы просмотреть эти почтовые сообщения, вы должны отправить их в приложение для тестирования электронной почты, например, MailHog или HELO.
Laravel позволяет отправлять почтовые сообщения, используя язык, отличный от текущего языка запроса, и даже будет помнить его, если почта находится в очереди.
Для этого фасад Mail содержит метод locale для установки желаемого языка. Приложение изменит язык при анализе шаблона почтового сообщения, а затем вернется к предыдущему языку, когда анализ будет завершен:
Mail::to($request->user())->locale('es')->send(
new OrderShipped($order)
);
Иногда приложения хранят предпочтительный язык каждого пользователя. Реализуя контракт HasLocalePreference в ваших моделях, вы можете указать Laravel использовать этот сохраненный язык при отправке почты:
use Illuminate\Contracts\Translation\HasLocalePreference;
class User extends Model implements HasLocalePreference
{
/**
* Получить предпочитаемую пользователем локализацию.
*
* @return string
*/
public function preferredLocale()
{
return $this->locale;
}
}
После того как вы реализовали интерфейс, Laravel будет автоматически использовать предпочтительный язык при отправке уведомлений и почтовых сообщений модели. Следовательно, при использовании этого интерфейса нет необходимости вызывать метод locale:
Mail::to($request->user())->send(new OrderShipped($order));
Laravel предлагает несколько удобных методов для тестирования того, что ваши почтовые сообщения содержат ожидаемый контент. Это следующие методы: assertSeeInHtml, assertDontSeeInHtml, assertSeeInText, и assertDontSeeInText.
Как и следовало ожидать, утверждения «HTML» утверждают, что HTML-версия вашего почтового сообщения содержит переданную строку, в то время как утверждения «текст» утверждают, что текстовая версия вашего почтового сообщения содержит переданную строку:
use App\Mail\InvoicePaid;
use App\Models\User;
public function test_mailable_content()
{
$user = User::factory()->create();
$mailable = new InvoicePaid($user);
$mailable->assertSeeInHtml($user->email);
$mailable->assertSeeInHtml('Invoice Paid');
$mailable->assertSeeInText($user->email);
$mailable->assertSeeInText('Invoice Paid');
}
Мы предлагаем тестировать содержимое ваших почтовых сообщений отдельно от тестов, которые подтверждают, что данное почтовое сообщение было «отправлено» определенному пользователю. Чтобы узнать, как протестировать, что почтовые отправления были отправлены, ознакомьтесь с нашей документацией по фальсификации Mail.
При разработке приложения для отправки электронной почты вы, вероятно, не захотите отправлять электронные письма на реальные адреса электронной почты. Laravel предлагает несколько способов «отключить» фактическую отправку электронных писем во время локальной разработки.
Вместо того чтобы отправлять ваши электронные письма, почтовый драйвер log будет записывать все сообщения электронной почты в ваши файлы журналов для проверки. Обычно этот драйвер используется только во время локальной разработки. Для получения дополнительной информации о настройке вашего приложения для каждой среды ознакомьтесь с документацией по конфигурации.
В качестве альтернативы вы можете использовать такую службу, как HELO или Mailtrap и драйвер smtp, чтобы отправлять сообщения электронной почты в «фиктивный» почтовый ящик, где вы можете просмотреть их в настоящем почтовом клиенте. Этот подход имеет то преимущество, что позволяет вам фактически проверять окончательные электронные письма, непосредственно в почтовых службах.
Если вы используете Laravel Sail, то вы можете предварительно просмотреть свои сообщения с помощью MailHog. Когда Sail запущен, вы можете получить доступ к интерфейсу MailHog по адресу: http://localhost:8025.
Наконец, вы можете указать глобальный адрес «кому», вызвав метод alwaysTo, предлагаемый фасадом Mail. Как правило, этот метод следует вызывать из метода boot одного из сервис-провайдеров вашего приложения:
use Illuminate\Support\Facades\Mail;
/**
* Bootstrap any application services.
*
* @return void
*/
public function boot()
{
if ($this->app->environment('local')) {
Mail::alwaysTo('[email protected]');
}
}
Laravel запускает два события в процессе отправки почтовых сообщений. Событие MessageSending запускается перед отправкой сообщения, а событие MessageSent запускается после того, как сообщение было отправлено. Помните, что эти события запускаются, когда почта отправляется, а не когда она ставится в очередь. Вы можете зарегистрировать слушатели для этого события в вашем поставщике App\Providers\EventServiceProvider:
/**
* Карта слушателей событий приложения.
*
* @var array
*/
protected $listen = [
'Illuminate\Mail\Events\MessageSending' => [
'App\Listeners\LogSendingMessage',
],
'Illuminate\Mail\Events\MessageSent' => [
'App\Listeners\LogSentMessage',
],
];