Пошта

• Вступ
  • Конфігурація
  • Вимоги до драйвера
  • Конфігурація резервування
  • Конфігурація Round Robin
• Генерація Mailables
• Написання Mailables
  • Налаштування Відправника
  • Налаштування Представлення
  • Дані шаблону
  • Вкладення
  • Вбудовані вкладення
  • Об'єкти, що приєднуються
  • Заголовки
  • Теги та метадані
  • Налаштування повідомлення Symfony
• Markdown Mailables
  • Генерація Markdown Mailables
  • Написання повідомлень у Markdown
  • Налаштування компонентів
• Відправка пошти
  • Черга Пошти
• Відображення Mailables
  • Перегляд Mailable в браузері
• Локалізація Mailables
• Тестування
  • Тестування вмісту Mailable
  • Тестування Відправки Mailable
• Пошта та локальна розробка
• Події
• Користувацькі транспорти
  • Додаткові транспорти Symfony

Вступ

Відправка електронної пошти не повинна бути складною. Laravel надає чистий, простий API для електронної пошти, що працює на популярному компоненті Symfony Mailer. Laravel і Symfony Mailer надають драйвери для відправки електронної пошти через SMTP, Mailgun, Postmark, Resend, Amazon SES і sendmail, що дозволяє швидко почати відправку пошти через локальний або хмарний сервіс на ваш вибір.

Конфігурація

Сервіси електронної пошти Laravel можуть бути налаштовані через файл конфігурації config/mail.php вашого застосунку. Кожен поштовий сервіс, налаштований у цьому файлі, може мати свою унікальну конфігурацію і навіть свій унікальний "транспорт", що дозволяє вашому застосунку використовувати різні сервіси електронної пошти для відправки певних електронних повідомлень. Наприклад, ваш застосунок може використовувати Postmark для відправки транзакційних листів, а Amazon SES для відправки масових листів.

У вашому файлі конфігурації mail ви знайдете масив конфігурації mailers. Цей масив містить зразок конфігурації для кожного з основних драйверів / транспортів пошти, які підтримуються Laravel, тоді як значення конфігурації default визначає, який mailer буде використовуватися за замовчуванням, коли вашому застосунку потрібно надіслати електронне повідомлення.

Драйвер / Вимоги до транспортування

API-базовані драйвери, такі як Mailgun, Postmark, Resend і MailerSend, часто є простішими та швидшими, ніж відправка пошти через SMTP-сервери. По можливості, ми рекомендуємо використовувати один з цих драйверів.

Драйвер Mailgun

Щоб використовувати драйвер Mailgun, встановіть транспорт Mailgun Mailer від Symfony через компонувальник:

composer require symfony/mailgun-mailer symfony/http-client

Далі, вам потрібно внести дві зміни у файл конфігурації config/mail.php вашого застосунку. Спочатку встановіть ваш поштовий драйвер за замовчуванням на mailgun:

'default' => env('MAIL_MAILER', 'mailgun'),

По-друге, додайте наступний масив конфігурації до вашого масиву mailers:

'mailgun' => [
    'transport' => 'mailgun',
    // 'client' => [
    //     'timeout' => 5,
    // ],
],

Після налаштування стандартного поштового сервісу вашого застосунку, додайте наступні параметри до вашого файлу конфігурації config/services.php:

'mailgun' => [
    'domain' => env('MAILGUN_DOMAIN'),
    'secret' => env('MAILGUN_SECRET'),
    'endpoint' => env('MAILGUN_ENDPOINT', 'api.mailgun.net'),
    'scheme' => 'https',
],

Якщо ви не використовуєте регіон Mailgun Сполучених Штатів, ви можете визначити кінцеву точку вашого регіону у файлі конфігурації services:

'mailgun' => [
    'domain' => env('MAILGUN_DOMAIN'),
    'secret' => env('MAILGUN_SECRET'),
    'endpoint' => env('MAILGUN_ENDPOINT', 'api.eu.mailgun.net'),
    'scheme' => 'https',
],

Драйвер Postmark

Щоб використовувати драйвер Postmark, встановіть транспорт Postmark Mailer від Symfony через компонувальник:

composer require symfony/postmark-mailer symfony/http-client

Далі встановіть опцію 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'),
    // 'client' => [
    //     'timeout' => 5,
    // ],
],

Таким чином, ви також можете налаштувати декілька поштових відправників Postmark з різними потоками повідомлень.

Resend драйвер

Щоб використовувати драйвер Resend, встановіть PHP SDK від Resend через компонувальник:

composer require resend/resend-php

Далі, встановіть опцію default у файлі конфігурації вашого застосунку config/mail.php на resend. Після налаштування стандартного поштового сервісу вашого застосунку, переконайтеся, що ваш файл конфігурації config/services.php містить наступні опції:

'resend' => [
    'key' => env('RESEND_KEY'),
],

SES Драйвер

Щоб використовувати драйвер 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'),
],

Щоб взаємодіяти з функціями управління підписками SES, ви можете повернути заголовок X-Ses-List-Management-Options у масиві, що повертається методом headers поштового повідомлення:

/**
 * Отримати заголовки повідомлення.
 */
public function headers(): Headers
{
    return new Headers(
        text: [
            'X-Ses-List-Management-Options' => 'contactListName=MyContactList;topicName=MyTopic',
        ],
    );
}

Якщо ви хочете визначити додаткові параметри, які Laravel повинен передати методу AWS SDK SendEmail при відправці електронної пошти, ви можете визначити масив 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',
        'EmailTags' => [
            ['Name' => 'foo', 'Value' => 'bar'],
        ],
    ],
],

Драйвер MailerSend

MailerSend, сервіс транзакційних електронних листів та SMS, підтримує власний драйвер пошти на основі API для Laravel. Пакет, що містить драйвер, може бути встановлений через менеджер пакетів компонувальник:

composer require mailersend/laravel-driver

Після встановлення пакета додайте змінну середовища MAILERSEND_API_KEY до файлу .env вашого застосунку. Крім того, змінна середовища MAIL_MAILER повинна бути визначена як mailersend:

MAIL_MAILER=mailersend
MAIL_FROM_ADDRESSexample@example.com
MAIL_FROM_NAME="App Name"
 
MAILERSEND_API_KEY=your-api-key

Нарешті, додайте MailerSend до масиву mailers у файлі конфігурації config/mail.php вашого застосунку:

'mailersend' => [
    'transport' => 'mailersend',
],

Щоб дізнатися більше про MailerSend, включаючи те, як використовувати розміщені шаблони, зверніться до документації драйвера MailerSend.

Конфігурація резервного перемикання

Іноді зовнішній сервіс, який ви налаштували для відправки пошти вашого застосунку, може бути недоступним. У таких випадках може бути корисно визначити одну або більше резервних конфігурацій доставки пошти, які будуть використовуватися, якщо ваш основний драйвер доставки не працює.

Щоб досягти цього, ви повинні визначити поштовий сервіс у файлі конфігурації mail вашого застосунку, який використовує транспорт failover. Конфігураційний масив для поштового сервісу failover вашого застосунку повинен містити масив mailers, який вказує порядок, у якому налаштовані поштові сервіси повинні бути обрані для доставки:

'mailers' => [
    'failover' => [
        'transport' => 'failover',
        'mailers' => [
            'postmark',
            'mailgun',
            'sendmail',
        ],
    ],
 
    // ...
],

Після того як ваш резервний поштовий сервіс визначено, ви повинні встановити цей поштовий сервіс як поштовий сервіс за замовчуванням, що використовується вашим застосунком, вказавши його ім'я як значення ключа конфігурації default у файлі конфігурації mail вашого застосунку:

'default' => env('MAIL_MAILER', 'failover'),

Конфігурація Round Robin

Транспорт roundrobin дозволяє розподілити навантаження на розсилку пошти між декількома поштовими сервісами. Щоб почати, визначте поштовий сервіс у файлі конфігурації mail вашого застосунку, який використовує транспорт roundrobin. Масив конфігурації для поштового сервісу roundrobin вашого застосунку повинен містити масив mailers, який вказує, які налаштовані поштові сервіси слід використовувати для доставки:

'mailers' => [
    'roundrobin' => [
        'transport' => 'roundrobin',
        'mailers' => [
            'ses',
            'postmark',
        ],
    ],
 
    // ...
],

Після того як ваш поштовий розсильник з круговим розподілом був визначений, ви повинні встановити цей розсильник як розсильник за замовчуванням, що використовується вашим застосунком, вказавши його ім'я як значення конфігураційного ключа default у файлі конфігурації mail вашого застосунку:

'default' => env('MAIL_MAILER', 'roundrobin'),

Транспорт з круговим чергуванням обирає випадковий поштовий сервіс з переліку налаштованих поштових сервісів, а потім переключається на наступний доступний поштовий сервіс для кожного наступного електронного листа. На відміну від транспорту failover, який допомагає досягти високої доступності, транспорт roundrobin забезпечує балансування навантаження.

Генерація Mailables

Коли ви створюєте Laravel застосунки, кожен тип електронної пошти, що надсилається вашим застосунком, представлений як клас "mailable". Ці класи зберігаються в директорії app/Mail. Не хвилюйтеся, якщо ви не бачите цю директорію у вашому застосунку, оскільки вона буде згенерована для вас, коли ви створите свій перший клас mailable за допомогою команди Artisan make:mail:

php artisan make:mail OrderShipped

Написання Mailables

Після того як ви згенерували клас mailable, відкрийте його, щоб ми могли дослідити його вміст. Налаштування класу mailable виконується в декількох методах, включаючи методи envelope, content та attachments.

Метод envelope повертає об'єкт Illuminate\Mail\Mailables\Envelope, який визначає тему і, іноді, одержувачів повідомлення. Метод content повертає об'єкт Illuminate\Mail\Mailables\Content, який визначає Blade шаблон, що буде використаний для генерації вмісту повідомлення.

Налаштування Відправника

Використання Envelope

Спочатку давайте розглянемо налаштування відправника електронної пошти. Або, іншими словами, від кого буде "від" електронна пошта. Існує два способи налаштування відправника. По-перше, ви можете вказати адресу "від" на конверті вашого повідомлення:

use Illuminate\Mail\Mailables\Address;
use Illuminate\Mail\Mailables\Envelope;
 
/**
 * Отримати конверт повідомлення.
 */
public function envelope(): Envelope
{
    return new Envelope(
        from: new Address('example@example.com', 'Jeffrey Way'),
        subject: 'Order Shipped',
    );
}

Якщо ви бажаєте, ви також можете вказати адресу replyTo:

return new Envelope(
    from: new Address('example@example.com', 'Jeffrey Way'),
    replyTo: [
        new Address('example@example.com', 'Taylor Otwell'),
    ],
    subject: 'Замовлення відправлено',
);

Використання глобальної адреси from

Однак, якщо ваш застосунок використовує ту саму адресу "from" для всіх своїх електронних листів, це може стати обтяжливим додавати її до кожного класу mailable, який ви створюєте. Замість цього, ви можете вказати глобальну адресу "from" у вашому конфігураційному файлі config/mail.php. Ця адреса буде використовуватися, якщо жодна інша адреса "from" не вказана в класі mailable:

'from' => [
    'address' => env('MAIL_FROM_ADDRESS', 'example@example.com'),
    'name' => env('MAIL_FROM_NAME', 'Example'),
],

Крім того, ви можете визначити глобальну адресу "reply_to" у вашому конфігураційному файлі config/mail.php:

'reply_to' => ['address' => 'example@example.com', 'name' => 'App Name'],

Налаштування Представлення

У методі content класу mailable ви можете визначити представлення, або який шаблон слід використовувати при рендерингу вмісту електронної пошти. Оскільки кожен електронний лист зазвичай використовує шаблон Blade для рендерингу свого вмісту, ви маєте всю потужність і зручність шаблонного двигуна Blade при створенні HTML вашої електронної пошти:

/**
 * Get the message content definition.
 */
public function content(): Content
{
    return new Content(
        view: 'mail.orders.shipped',
    );
}

Текстові електронні листи

Якщо ви хочете визначити версію вашого електронного листа у вигляді простого тексту, ви можете вказати шаблон простого тексту при створенні визначення Content повідомлення. Як і параметр view, параметр text повинен бути назвою шаблону, який буде використовуватися для відображення вмісту електронного листа. Ви можете вільно визначити як HTML, так і версію вашого повідомлення у вигляді простого тексту:

/**
 * Отримати визначення вмісту повідомлення.
 */
public function content(): Content
{
    return new Content(
        view: 'mail.orders.shipped',
        text: 'mail.orders.shipped-text'
    );
}

Для ясності, параметр html може бути використаний як псевдонім параметра представлення:

return new Content(
    html: 'mail.orders.shipped',
    text: 'mail.orders.shipped-text'
);

Дані шаблону

Через Публічні Властивості

Зазвичай, ви захочете передати деякі дані до вашого представлення, які ви можете використовувати при рендерингу HTML електронної пошти. Існує два способи, якими ви можете зробити дані доступними для вашого представлення. По-перше, будь-яка публічна властивість, визначена у вашому класі mailable, автоматично буде доступна для представлення. Отже, наприклад, ви можете передати дані в конструктор вашого класу mailable і встановити ці дані в публічні властивості, визначені в класі:

<?php
 
namespace App\Mail;
 
use App\Models\Order;
use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Mail\Mailables\Content;
use Illuminate\Queue\SerializesModels;
 
class OrderShipped extends Mailable
{
    use Queueable, SerializesModels;
 
    /**
     * Створити новий екземпляр повідомлення.
     */
    public function __construct(
        public Order $order,
    ) {}
 
    /**
     * Отримати визначення вмісту повідомлення.
     */
    public function content(): Content
    {
        return new Content(
            view: 'mail.orders.shipped',
        );
    }
}

Як тільки дані будуть встановлені в публічну властивість, вони автоматично будуть доступні у вашому представленні, тому ви можете отримати до них доступ так само, як ви отримуєте доступ до будь-яких інших даних у ваших Blade-шаблонах:

<div>
    Ціна: {{ $order->price }}
</div>

Через параметр with:

Якщо ви хочете налаштувати формат даних вашого електронного листа перед тим, як вони будуть відправлені до шаблону, ви можете вручну передати ваші дані до представлення через параметр with визначення Content. Зазвичай ви все ще передаватимете дані через конструктор класу mailable; однак, ви повинні встановити ці дані як protected або private властивості, щоб дані не були автоматично доступні для шаблону:

<?php
 
namespace App\Mail;
 
use App\Models\Order;
use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Mail\Mailables\Content;
use Illuminate\Queue\SerializesModels;
 
class OrderShipped extends Mailable
{
    use Queueable, SerializesModels;
 
    /**
     * Створити новий екземпляр повідомлення.
     */
    public function __construct(
        protected Order $order,
    ) {}
 
    /**
     * Отримати визначення вмісту повідомлення.
     */
    public function content(): Content
    {
        return new Content(
            view: 'mail.orders.shipped',
            with: [
                'orderName' => $this->order->name,
                'orderPrice' => $this->order->price,
            ],
        );
    }
}

Після того як дані були передані методу with, вони автоматично будуть доступні у вашому представленні, тому ви можете отримати до них доступ так само, як і до будь-яких інших даних у ваших шаблонах Blade:

<div>
    Ціна: {{ $orderPrice }}
</div>

Вкладення

Щоб додати вкладення до електронного листа, ви додасте вкладення до масиву, що повертається методом attachments повідомлення. Спочатку ви можете додати вкладення, надавши шлях до файлу методу fromPath, наданого класом Attachment:

use Illuminate\Mail\Mailables\Attachment;
 
/**
 * Отримати вкладення для повідомлення.
 *
 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
 */
public function attachments(): array
{
    return [
        Attachment::fromPath('/path/to/file'),
    ];
}

Коли додаєте файли до повідомлення, ви також можете вказати відображуване ім'я та / або MIME-тип для вкладення, використовуючи методи as та withMime:

/**
 * Отримати вкладення для повідомлення.
 *
 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
 */
public function attachments(): array
{
    return [
        Attachment::fromPath('/path/to/file')
            ->as('name.pdf')
            ->withMime('application/pdf'),
    ];
}

Прикріплення файлів з диска

Якщо ви зберегли файл на одному з ваших дисків файлової системи, ви можете прикріпити його до електронної пошти, використовуючи метод прикріплення fromStorage:

/**
 * Отримати вкладення для повідомлення.
 *
 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
 */
public function attachments(): array
{
    return [
        Attachment::fromStorage('/path/to/file'),
    ];
}

Звичайно, ви також можете вказати ім'я вкладення та MIME-тип:

/**
 * Отримати вкладення для повідомлення.
 *
 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
 */
public function attachments(): array
{
    return [
        Attachment::fromStorage('/path/to/file')
            ->as('name.pdf')
            ->withMime('application/pdf'),
    ];
}

Метод fromStorageDisk може бути використаний, якщо вам потрібно вказати диск зберігання, відмінний від вашого диска за замовчуванням:

/**
 * Отримати вкладення для повідомлення.
 *
 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
 */
public function attachments(): array
{
    return [
        Attachment::fromStorageDisk('s3', '/path/to/file')
            ->as('name.pdf')
            ->withMime('application/pdf'),
    ];
}

Сирі дані вкладення

Метод вкладення fromData може бути використаний для прикріплення сирого рядка байтів як вкладення. Наприклад, ви можете використовувати цей метод, якщо ви створили PDF у пам'яті і хочете прикріпити його до електронної пошти без запису на диск. Метод fromData приймає замикання, яке вирішує сирі байти даних, а також ім'я, яке має бути призначене вкладенню:

/**
 * Отримати вкладення для повідомлення.
 *
 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
 */
public function attachments(): array
{
    return [
        Attachment::fromData(fn () => $this->pdf, 'Report.pdf')
            ->withMime('application/pdf'),
    ];
}

Вбудовані вкладення

Вбудовування зображень у ваші електронні листи зазвичай є складним завданням; однак Laravel надає зручний спосіб прикріплення зображень до ваших листів. Щоб вбудувати зображення, використовуйте метод embed на змінній $message у вашому шаблоні електронної пошти. Laravel автоматично робить змінну $message доступною для всіх ваших шаблонів електронної пошти, тому вам не потрібно турбуватися про її передачу вручну:

<body>
    Ось картинка:
 
    <img src="{{ $message->embed($pathToImage) }}">
</body>

Вбудовування необроблених даних вкладень

Якщо у вас вже є рядок з необробленими даними зображення, який ви хочете вбудувати в шаблон електронної пошти, ви можете викликати метод embedData на змінній $message. При виклику методу embedData вам потрібно буде надати ім'я файлу, яке має бути призначене вбудованому зображенню:

<body>
    Ось зображення з необроблених даних:
 
    <img src="{{ $message->embedData($data, 'example-image.jpg') }}">
</body>

Об'єкти, що приєднуються

Хоча прикріплення файлів до повідомлень за допомогою простих рядкових шляхів часто є достатнім, у багатьох випадках прикріплювані сутності у вашому застосунку представлені класами. Наприклад, якщо ваш застосунок прикріплює фото до повідомлення, ваш застосунок може також мати модель Photo, яка представляє це фото. У такому випадку, чи не було б зручно просто передати модель Photo до методу attach? Об'єкти, які можна прикріпити, дозволяють вам зробити саме це.

Щоб почати, реалізуйте інтерфейс Illuminate\Contracts\Mail\Attachable на об'єкті, який буде прикріплюваним до повідомлень. Цей інтерфейс вимагає, щоб ваш клас визначав метод toMailAttachment, який повертає екземпляр Illuminate\Mail\Attachment:

<?php
 
namespace App\Models;
 
use Illuminate\Contracts\Mail\Attachable;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Mail\Attachment;
 
class Photo extends Model implements Attachable
{
    /**
     * Отримати представлення моделі, яке можна прикріпити.
     */
    public function toMailAttachment(): Attachment
    {
        return Attachment::fromPath('/path/to/file');
    }
}

Після того як ви визначили ваш об'єкт, що може бути прикріплений, ви можете повернути екземпляр цього об'єкта з методу attachments при створенні електронного повідомлення:

/**
 * Отримати вкладення для повідомлення.
 *
 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
 */
public function attachments(): array
{
    return [$this->photo];
}

Звичайно, дані вкладень можуть зберігатися на віддаленому сервісі зберігання файлів, такому як Amazon S3. Тому Laravel також дозволяє створювати екземпляри вкладень з даних, які зберігаються на одному з дисків файлової системи вашого застосунку:

// Створіть вкладення з файлу на вашому диску за замовчуванням...
return Attachment::fromStorage($this->path);
 
// Створіть вкладення з файлу на конкретному диску...
return Attachment::fromStorageDisk('backblaze', $this->path);

Крім того, ви можете створювати екземпляри вкладень за допомогою даних, які у вас є в пам'яті. Щоб це зробити, надайте замикання методу fromData. Замикання має повертати необроблені дані, які представляють вкладення:

return Attachment::fromData(fn () => $this->content, 'Photo Name');

Laravel також надає додаткові методи, які ви можете використовувати для налаштування ваших вкладень. Наприклад, ви можете використовувати методи as та withMime для налаштування імені файлу та MIME типу:

return Attachment::fromPath('/path/to/file')
    ->as('Photo Name')
    ->withMime('image/jpeg');

Заголовки

Іноді вам може знадобитися додати додаткові заголовки до вихідного повідомлення. Наприклад, вам може знадобитися встановити користувацький Message-Id або інші довільні текстові заголовки.

Щоб досягти цього, визначте метод headers у вашому mailable. Метод headers повинен повертати екземпляр Illuminate\Mail\Mailables\Headers. Цей клас приймає параметри messageId, references та text. Звісно, ви можете надати лише ті параметри, які вам потрібні для вашого конкретного повідомлення:

use Illuminate\Mail\Mailables\Headers;
 
/**
 * Отримати заголовки повідомлення.
 */
public function headers(): Headers
{
    return new Headers(
        messageId: 'example@example.com',
        references: ['example@example.com'],
        text: [
            'X-Custom-Header' => 'Custom Value',
        ],
    );
}

Теги та метадані

Деякі сторонні постачальники електронної пошти, такі як Mailgun та Postmark, підтримують "теги" та "метадані" повідомлень, які можуть використовуватися для групування та відстеження електронних листів, надісланих вашим застосунком. Ви можете додати теги та метадані до електронного повідомлення через ваше визначення Envelope:

use Illuminate\Mail\Mailables\Envelope;
 
/**
 * Отримати конверт повідомлення.
 *
 * @return \Illuminate\Mail\Mailables\Envelope
 */
public function envelope(): Envelope
{
    return new Envelope(
        subject: 'Order Shipped',
        tags: ['shipment'],
        metadata: [
            'order_id' => $this->order->id,
        ],
    );
}

Якщо ваш застосунок використовує драйвер Mailgun, ви можете звернутися до документації Mailgun для отримання додаткової інформації про теги та метадані. Так само, ви можете звернутися до документації Postmark для отримання додаткової інформації про їх підтримку тегів та метаданих.

Якщо ваш застосунок використовує Amazon SES для відправки електронних листів, ви повинні використовувати метод metadata для прикріплення "тегів" SES до повідомлення.

Налаштування повідомлення Symfony

Можливості пошти Laravel забезпечуються Symfony Mailer. Laravel дозволяє реєструвати власні зворотні виклики, які будуть викликані з екземпляром Symfony Message перед відправкою повідомлення. Це дає вам можливість глибоко налаштувати повідомлення перед його відправкою. Щоб досягти цього, визначте параметр using у вашому визначенні Envelope:

use Illuminate\Mail\Mailables\Envelope;
use Symfony\Component\Mime\Email;
 
/**
 * Отримати конверт повідомлення.
 */
public function envelope(): Envelope
{
    return new Envelope(
        subject: 'Order Shipped',
        using: [
            function (Email $message) {
                // ...
            },
        ]
    );
}

Markdown Поштові повідомлення

Markdown повідомлення, що надсилаються, дозволяють скористатися перевагами попередньо створених шаблонів і компонентів поштових сповіщень у ваших mailables. Оскільки повідомлення написані на Markdown, Laravel може відображати красиві, адаптивні HTML-шаблони для повідомлень, а також автоматично генерувати текстову версію.

Генерація Markdown Mailables

Щоб згенерувати mailable з відповідним шаблоном Markdown, ви можете використовувати опцію --markdown команди Artisan make:mail:

php artisan make:mail OrderShipped --markdown=mail.orders.shipped

Потім, при налаштуванні визначення Content у методі content, використовуйте параметр markdown замість параметра представлення:

use Illuminate\Mail\Mailables\Content;
 
/**
 * Отримати визначення вмісту листа.
 */
public function content(): Content
{
    return new Content(
        markdown: 'mail.orders.shipped',
        with: [
            'url' => $this->orderUrl,
        ],
    );
}

Написання повідомлень у Markdown

Markdown поштові повідомлення використовують комбінацію компонентів Blade та синтаксису Markdown, що дозволяє легко створювати поштові повідомлення, використовуючи попередньо створені компоненти інтерфейсу електронної пошти Laravel:

<x-mail::message>
# Замовлення відправлено
 
Ваше замовлення було відправлено!
 
<x-mail::button :url="$url">
Переглянути замовлення
</x-mail::button>
 
Дякуємо,<br>
{{ config('app.name') }}
</x-mail::message>

Компонент кнопки

Компонент кнопки відображає центроване посилання-кнопку. Компонент приймає два аргументи: url та необов'язковий color. Підтримувані кольори: primary, success та error. Ви можете додати до повідомлення стільки компонентів кнопок, скільки забажаєте:

<x-mail::button :url="$url" color="success">
Переглянути замовлення
</x-mail::button>

Компонент панелі

Компонент панелі відображає заданий блок тексту в панелі, яка має трохи інший колір фону, ніж решта повідомлення. Це дозволяє привернути увагу до заданого блоку тексту:

<x-mail::panel>
Це вміст панелі.
</x-mail::panel>

Компонент таблиці

Компонент таблиці дозволяє перетворити таблицю Markdown у таблицю HTML. Компонент приймає таблицю Markdown як свій вміст. Вирівнювання стовпців таблиці підтримується за допомогою стандартного синтаксису вирівнювання таблиць Markdown:

<x-mail::table>
| Laravel       | Table         | Example       |
| ------------- | :-----------: | ------------: |
| Col 2 is      | Centered      | $10           |
| Col 3 is      | Right-Aligned | $20           |
</x-mail::table>

Налаштування компонентів

Ви можете експортувати всі компоненти пошти у форматі Markdown до вашого власного застосунку для налаштування. Щоб експортувати компоненти, використовуйте команду Artisan vendor:publish для публікації тегу ресурсу laravel-mail:

php artisan vendor:publish --tag=laravel-mail

Ця команда опублікує компоненти пошти Markdown у директорії resources/views/vendor/mail. Директорія mail міститиме директорії html та text, кожна з яких міститиме відповідні представлення кожного доступного компонента. Ви можете налаштовувати ці компоненти на свій розсуд.

Налаштування CSS

Після експорту компонентів, директорія resources/views/vendor/mail/html/themes міститиме файл default.css. Ви можете налаштувати CSS у цьому файлі, і ваші стилі автоматично будуть перетворені на вбудовані CSS стилі в HTML представленнях ваших Markdown поштових повідомлень.

Якщо ви хочете створити абсолютно нову тему для компонентів Markdown у Laravel, ви можете розмістити CSS-файл у каталозі html/themes. Після того, як ви назвете та збережете свій CSS-файл, оновіть параметр theme у конфігураційному файлі config/mail.php вашого застосунку, щоб він відповідав назві вашої нової теми.

Щоб налаштувати тему для окремого mailable, ви можете встановити властивість $theme класу mailable на ім'я теми, яка повинна використовуватися при відправці цього mailable.

Відправка Пошти

Щоб надіслати повідомлення, використовуйте метод to на Mail фасаді. Метод to приймає адресу електронної пошти, екземпляр користувача або колекцію користувачів. Якщо ви передаєте об'єкт або колекцію об'єктів, поштовий сервіс автоматично використовуватиме їхні властивості email та name для визначення одержувачів електронної пошти, тому переконайтеся, що ці атрибути доступні у ваших об'єктах. Після того, як ви вказали одержувачів, ви можете передати екземпляр вашого класу для надсилання на метод send:

<?php
 
namespace App\Http\Controllers;
 
use App\Mail\OrderShipped;
use App\Models\Order;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Mail;
 
class OrderShipmentController extends Controller
{
    /**
     * Відправити дане замовлення.
     */
    public function store(Request $request): RedirectResponse
    {
        $order = Order::findOrFail($request->order_id);
 
        // Відправити замовлення...
 
        Mail::to($request->user())->send(new OrderShipped($order));
 
        return redirect('/orders');
    }
}

Ви не обмежені лише вказанням одержувачів "to" при відправленні повідомлення. Ви можете вільно встановлювати одержувачів "to", "cc" та "bcc", поєднуючи їх відповідні методи разом:

Mail::to($request->user())
    ->cc($moreUsers)
    ->bcc($evenMoreUsers)
    ->send(new OrderShipped($order));

Перебір Отримувачів

Іноді вам може знадобитися надіслати листа на список одержувачів, перебираючи масив одержувачів / електронних адрес. Однак, оскільки метод to додає електронні адреси до списку одержувачів листа, кожна ітерація через цикл надішле ще один лист кожному попередньому одержувачу. Тому ви завжди повинні заново створювати екземпляр листа для кожного одержувача:

foreach (['example@example.com', 'example@example.com'] 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
{
    // ...
}

Черга для відправки листів та транзакції бази даних

Коли відправляються queued mailables у межах транзакцій бази даних, вони можуть бути оброблені чергою до того, як транзакція бази даних буде зафіксована. Коли це відбувається, будь-які оновлення, які ви зробили в моделях або записах бази даних під час транзакції, можуть ще не відображатися в базі даних. Крім того, будь-які моделі або записи бази даних, створені в межах транзакції, можуть не існувати в базі даних. Якщо ваш mailable залежить від цих моделей, можуть виникнути несподівані помилки, коли завдання, яке відправляє queued mailable, буде оброблено.

Якщо параметр конфігурації after_commit вашого з'єднання черги встановлено на false, ви все ще можете вказати, що певний відкладений у чергу лист має бути відправлений після того, як всі відкриті транзакції бази даних будуть зафіксовані, викликавши метод afterCommit при відправленні поштового повідомлення:

Mail::to($request->user())->send(
    (new OrderShipped($order))->afterCommit()
);

Альтернативно, ви можете викликати метод afterCommit з конструктора вашого mailable:

<?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;
 
    /**
     * Створити новий екземпляр повідомлення.
     */
    public function __construct()
    {
        $this->afterCommit();
    }
}

Збої черги електронної пошти

Коли відправка електронного листа в черзі зазнає невдачі, буде викликано метод failed у класі mailable в черзі, якщо він був визначений. Екземпляр Throwable, який спричинив невдачу відправки електронного листа в черзі, буде передано методу failed:

<?php
 
namespace App\Mail;
 
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Mail\Mailable;
use Illuminate\Queue\SerializesModels;
use Throwable;
 
class OrderDelayed extends Mailable implements ShouldQueue
{
    use SerializesModels;
 
    /**
     * Обробити збій відправлення листа з черги.
     */
    public function failed(Throwable $exception): void
    {
        // ...
    }
}

Відображення Mailables

Іноді ви можете захотіти отримати HTML-вміст листа без його відправлення. Для цього ви можете викликати метод render листа. Цей метод поверне оцінений HTML-вміст листа у вигляді рядка:

use App\Mail\InvoicePaid;
use App\Models\Invoice;
 
$invoice = Invoice::find(1);
 
return (new InvoicePaid($invoice))->render();

Перегляд Mailable у браузері

Коли ви розробляєте шаблон для поштового повідомлення, зручно швидко переглянути відображене поштове повідомлення у вашому браузері, як типовий шаблон Blade. З цієї причини Laravel дозволяє повертати будь-яке поштове повідомлення безпосередньо з замикання маршруту або контролера. Коли поштове повідомлення повертається, воно буде відображено та показано у браузері, що дозволяє швидко переглянути його дизайн без необхідності відправляти його на фактичну електронну адресу:

Route::get('/mailable', function () {
    $invoice = App\Models\Invoice::find(1);
 
    return new App\Mail\InvoicePaid($invoice);
});

Локалізація Mailables

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
{
    /**
     * Отримати бажану локаль користувача.
     */
    public function preferredLocale(): string
    {
        return $this->locale;
    }
}

Як тільки ви реалізуєте інтерфейс, Laravel автоматично використовуватиме бажану локаль при відправленні поштових повідомлень та сповіщень до моделі. Тому немає потреби викликати метод locale при використанні цього інтерфейсу:

Mail::to($request->user())->send(new OrderShipped($order));

Тестування

Тестування вмісту Mailable

Laravel надає різноманітні методи для перевірки структури вашого mailable. Крім того, Laravel надає кілька зручних методів для тестування, що ваш mailable містить очікуваний вміст. Ці методи: assertSeeInHtml, assertDontSeeInHtml, assertSeeInOrderInHtml, assertSeeInText, assertDontSeeInText, assertSeeInOrderInText, assertHasAttachment, assertHasAttachedData, assertHasAttachmentFromStorage та assertHasAttachmentFromStorageDisk.

Як ви могли очікувати, твердження "HTML" перевіряють, що HTML-версія вашого листа містить заданий рядок, тоді як твердження "text" перевіряють, що текстова версія вашого листа містить заданий рядок:

use App\Mail\InvoicePaid;
use App\Models\User;
 
test('mailable content', function () {
    $user = User::factory()->create();
 
    $mailable = new InvoicePaid($user);
 
    $mailable->assertFrom('example@example.com');
    $mailable->assertTo('example@example.com');
    $mailable->assertHasCc('example@example.com');
    $mailable->assertHasBcc('example@example.com');
    $mailable->assertHasReplyTo('example@example.com');
    $mailable->assertHasSubject('Invoice Paid');
    $mailable->assertHasTag('example-tag');
    $mailable->assertHasMetadata('key', 'value');
 
    $mailable->assertSeeInHtml($user->email);
    $mailable->assertSeeInHtml('Invoice Paid');
    $mailable->assertSeeInOrderInHtml(['Invoice Paid', 'Thanks']);
 
    $mailable->assertSeeInText($user->email);
    $mailable->assertSeeInOrderInText(['Invoice Paid', 'Thanks']);
 
    $mailable->assertHasAttachment('/path/to/file');
    $mailable->assertHasAttachment(Attachment::fromPath('/path/to/file'));
    $mailable->assertHasAttachedData($pdfData, 'name.pdf', ['mime' => 'application/pdf']);
    $mailable->assertHasAttachmentFromStorage('/path/to/file', 'name.pdf', ['mime' => 'application/pdf']);
    $mailable->assertHasAttachmentFromStorageDisk('s3', '/path/to/file', 'name.pdf', ['mime' => 'application/pdf']);
});

use App\Mail\InvoicePaid;
use App\Models\User;
 
public function test_mailable_content(): void
{
    $user = User::factory()->create();
 
    $mailable = new InvoicePaid($user);
 
    $mailable->assertFrom('example@example.com');
    $mailable->assertTo('example@example.com');
    $mailable->assertHasCc('example@example.com');
    $mailable->assertHasBcc('example@example.com');
    $mailable->assertHasReplyTo('example@example.com');
    $mailable->assertHasSubject('Invoice Paid');
    $mailable->assertHasTag('example-tag');
    $mailable->assertHasMetadata('key', 'value');
 
    $mailable->assertSeeInHtml($user->email);
    $mailable->assertSeeInHtml('Invoice Paid');
    $mailable->assertSeeInOrderInHtml(['Invoice Paid', 'Thanks']);
 
    $mailable->assertSeeInText($user->email);
    $mailable->assertSeeInOrderInText(['Invoice Paid', 'Thanks']);
 
    $mailable->assertHasAttachment('/path/to/file');
    $mailable->assertHasAttachment(Attachment::fromPath('/path/to/file'));
    $mailable->assertHasAttachedData($pdfData, 'name.pdf', ['mime' => 'application/pdf']);
    $mailable->assertHasAttachmentFromStorage('/path/to/file', 'name.pdf', ['mime' => 'application/pdf']);
    $mailable->assertHasAttachmentFromStorageDisk('s3', '/path/to/file', 'name.pdf', ['mime' => 'application/pdf']);
}

Тестування Відправки Mailable

Ми рекомендуємо тестувати вміст ваших поштових повідомлень окремо від ваших тестів, які стверджують, що певне поштове повідомлення було "надіслано" конкретному користувачу. Зазвичай, вміст поштових повідомлень не є релевантним до коду, який ви тестуєте, і достатньо просто стверджувати, що Laravel було проінструктовано надіслати певне поштове повідомлення.

Ви можете використовувати метод fake фасаду Mail, щоб запобігти відправленню пошти. Після виклику методу fake фасаду Mail, ви можете перевірити, що поштові повідомлення були інструктовані для відправки користувачам і навіть перевірити дані, які отримали поштові повідомлення:

<?php
 
use App\Mail\OrderShipped;
use Illuminate\Support\Facades\Mail;
 
test('orders can be shipped', function () {
    Mail::fake();
 
    // Виконати відправлення замовлення...
 
    // Перевірити, що жодного листа не було надіслано...
    Mail::assertNothingSent();
 
    // Перевірити, що лист був надісланий...
    Mail::assertSent(OrderShipped::class);
 
    // Перевірити, що лист був надісланий двічі...
    Mail::assertSent(OrderShipped::class, 2);
 
    // Перевірити, що лист був надісланий на адресу електронної пошти...
    Mail::assertSent(OrderShipped::class, 'example@example.com');
 
    // Перевірити, що лист був надісланий на кілька адрес електронної пошти...
    Mail::assertSent(OrderShipped::class, ['example@example.com', '...']);
 
    // Перевірити, що лист не був надісланий...
    Mail::assertNotSent(AnotherMailable::class);
 
    // Перевірити, що загалом було надіслано 3 листи...
    Mail::assertSentCount(3);
});

<?php
 
namespace Tests\Feature;
 
use App\Mail\OrderShipped;
use Illuminate\Support\Facades\Mail;
use Tests\TestCase;
 
class ExampleTest extends TestCase
{
    public function test_orders_can_be_shipped(): void
    {
        Mail::fake();
 
        // Виконати відправлення замовлення...
 
        // Перевірити, що жодного листа не було надіслано...
        Mail::assertNothingSent();
 
        // Перевірити, що лист був надісланий...
        Mail::assertSent(OrderShipped::class);
 
        // Перевірити, що лист був надісланий двічі...
        Mail::assertSent(OrderShipped::class, 2);
 
        // Перевірити, що лист був надісланий на адресу електронної пошти...
        Mail::assertSent(OrderShipped::class, 'example@example.com');
 
        // Перевірити, що лист був надісланий на кілька адрес електронної пошти...
        Mail::assertSent(OrderShipped::class, ['example@example.com', '...']);
 
        // Перевірити, що лист не був надісланий...
        Mail::assertNotSent(AnotherMailable::class);
 
        // Перевірити, що загалом було надіслано 3 листи...
        Mail::assertSentCount(3);
    }
}

Якщо ви ставите в чергу mailables для доставки у фоновому режимі, ви повинні використовувати метод assertQueued замість assertSent:

Mail::assertQueued(OrderShipped::class);
Mail::assertNotQueued(OrderShipped::class);
Mail::assertNothingQueued();
Mail::assertQueuedCount(3);

Ви можете передати замикання до методів assertSent, assertNotSent, assertQueued або assertNotQueued, щоб перевірити, що mailable було відправлено, яке проходить заданий "тест істинності". Якщо було відправлено принаймні одне mailable, яке проходить заданий тест істинності, тоді перевірка буде успішною:

Mail::assertSent(function (OrderShipped $mail) use ($order) {
    return $mail->order->id === $order->id;
});

Коли викликаються методи перевірки фасаду Mail, екземпляр mailable, прийнятий наданим замиканням, надає корисні методи для перевірки mailable:

Mail::assertSent(OrderShipped::class, function (OrderShipped $mail) use ($user) {
    return $mail->hasTo($user->email) &&
           $mail->hasCc('...') &&
           $mail->hasBcc('...') &&
           $mail->hasReplyTo('...') &&
           $mail->hasFrom('...') &&
           $mail->hasSubject('...');
});

Екземпляр mailable також включає кілька корисних методів для перевірки вкладень у mailable:

use Illuminate\Mail\Mailables\Attachment;
 
Mail::assertSent(OrderShipped::class, function (OrderShipped $mail) {
    return $mail->hasAttachment(
        Attachment::fromPath('/path/to/file')
            ->as('name.pdf')
            ->withMime('application/pdf')
    );
});
 
Mail::assertSent(OrderShipped::class, function (OrderShipped $mail) {
    return $mail->hasAttachment(
        Attachment::fromStorageDisk('s3', '/path/to/file')
    );
});
 
Mail::assertSent(OrderShipped::class, function (OrderShipped $mail) use ($pdfData) {
    return $mail->hasAttachment(
        Attachment::fromData(fn () => $pdfData, 'name.pdf')
    );
});

Ви могли помітити, що існують два методи для перевірки, що пошта не була відправлена: assertNotSent та assertNotQueued. Іноді ви можете захотіти перевірити, що жодна пошта не була відправлена або поставлена в чергу. Для цього ви можете використовувати методи assertNothingOutgoing та assertNotOutgoing:

Mail::assertNothingOutgoing();
 
Mail::assertNotOutgoing(function (OrderShipped $mail) use ($order) {
    return $mail->order->id === $order->id;
});

Пошта та локальна розробка

Коли ви розробляєте застосунок, що надсилає електронні листи, ви, ймовірно, не хочете насправді надсилати листи на реальні електронні адреси. Laravel надає кілька способів "відключити" фактичне надсилання електронних листів під час локальної розробки.

Драйвер журналу

Замість відправки ваших електронних листів, драйвер пошти log буде записувати всі повідомлення електронної пошти у ваші файли журналів для перевірки. Зазвичай цей драйвер використовується лише під час локальної розробки. Для отримання додаткової інформації про налаштування вашого застосунку для кожного середовища, перегляньте документацію з налаштування.

HELO / Mailtrap / Mailpit

Альтернативно, ви можете використовувати сервіс, такий як HELO або Mailtrap і драйвер smtp для відправки ваших електронних повідомлень до "тестової" поштової скриньки, де ви можете переглядати їх у справжньому поштовому клієнті. Цей підхід має перевагу, оскільки дозволяє вам фактично перевіряти фінальні електронні листи у переглядачі повідомлень Mailtrap.

Якщо ви використовуєте Laravel Sail, ви можете переглядати ваші повідомлення за допомогою Mailpit. Коли Sail запущено, ви можете отримати доступ до інтерфейсу Mailpit за адресою: http://localhost:8025.

Використання глобальної адреси to

Нарешті, ви можете вказати глобальну адресу "to", викликавши метод alwaysTo, запропонований фасадом Mail. Зазвичай цей метод слід викликати з методу boot одного з сервіс-провайдерів вашого застосунку:

use Illuminate\Support\Facades\Mail;
 
/**
 * Ініціалізувати будь-які сервіси застосунку.
 */
public function boot(): void
{
    if ($this->app->environment('local')) {
        Mail::alwaysTo('example@example.com');
    }
}

Події

Laravel відправляє дві події під час надсилання поштових повідомлень. Подія MessageSending відправляється перед тим, як повідомлення буде надіслано, тоді як подія MessageSent відправляється після того, як повідомлення було надіслано. Пам'ятайте, ці події відправляються, коли пошта надсилається, а не коли вона ставиться в чергу. Ви можете створити слухачі подій для цих подій у вашому застосунку:

use Illuminate\Mail\Events\MessageSending;
// use Illuminate\Mail\Events\MessageSent;
 
class LogMessage
{
    /**
     * Обробити подію.
     */
    public function handle(MessageSending $event): void
    {
        // ...
    }
}

Користувацькі Транспорти

Laravel включає різноманітні транспорти для пошти; однак, ви можете захотіти написати власні транспорти для доставки електронної пошти через інші сервіси, які Laravel не підтримує з коробки. Щоб почати, визначте клас, який розширює клас Symfony\Component\Mailer\Transport\AbstractTransport. Потім реалізуйте методи doSend та __toString() у вашому транспорті:

use MailchimpTransactional\ApiClient;
use Symfony\Component\Mailer\SentMessage;
use Symfony\Component\Mailer\Transport\AbstractTransport;
use Symfony\Component\Mime\Address;
use Symfony\Component\Mime\MessageConverter;
 
class MailchimpTransport extends AbstractTransport
{
    /**
     * Створити новий екземпляр транспорту Mailchimp.
     */
    public function __construct(
        protected ApiClient $client,
    ) {
        parent::__construct();
    }
 
    /**
     * {@inheritDoc}
     */
    protected function doSend(SentMessage $message): void
    {
        $email = MessageConverter::toEmail($message->getOriginalMessage());
 
        $this->client->messages->send(['message' => [
            'from_email' => $email->getFrom(),
            'to' => collect($email->getTo())->map(function (Address $email) {
                return ['email' => $email->getAddress(), 'type' => 'to'];
            })->all(),
            'subject' => $email->getSubject(),
            'text' => $email->getTextBody(),
        ]]);
    }
 
    /**
     * Отримати рядкове представлення транспорту.
     */
    public function __toString(): string
    {
        return 'mailchimp';
    }
}

Після того як ви визначили свій власний транспорт, ви можете зареєструвати його за допомогою методу extend, наданого фасадом Mail. Зазвичай це слід робити в методі boot сервіс-провайдера AppServiceProvider вашого застосунку. Аргумент $config буде передано в замикання, надане методу extend. Цей аргумент міститиме масив конфігурації, визначений для поштового сервісу у файлі конфігурації config/mail.php вашого застосунку:

use App\Mail\MailchimpTransport;
use Illuminate\Support\Facades\Mail;
 
/**
 * Завантажте будь-які сервіси застосунку.
 */
public function boot(): void
{
    Mail::extend('mailchimp', function (array $config = []) {
        return new MailchimpTransport(/* ... */);
    });
}

Після того як ваш власний транспорт було визначено та зареєстровано, ви можете створити визначення поштовика у файлі конфігурації вашого застосунку config/mail.php, яке використовує новий транспорт:

'mailchimp' => [
    'transport' => 'mailchimp',
    // ...
],

Додаткові транспорти Symfony

Laravel включає підтримку деяких існуючих транспортів пошти, які підтримуються Symfony, таких як Mailgun і Postmark. Однак, ви можете розширити Laravel, додавши підтримку додаткових транспортів, які підтримуються Symfony. Ви можете зробити це, вимагаючи необхідний поштовий компонент Symfony через компонувальник і реєструючи транспорт у Laravel. Наприклад, ви можете встановити та зареєструвати поштовий компонент Symfony "Brevo" (раніше "Sendinblue"):

composer require symfony/brevo-mailer symfony/http-client

Після встановлення пакету Brevo mailer, ви можете додати запис для ваших облікових даних Brevo API до конфігураційного файлу services вашого застосунку:

'brevo' => [
    'key' => 'your-api-key',
],

Далі, ви можете використати метод extend фасаду Mail для реєстрації транспорту в Laravel. Зазвичай це слід робити в методі boot Сервіс-провайдера:

use Illuminate\Support\Facades\Mail;
use Symfony\Component\Mailer\Bridge\Brevo\Transport\BrevoTransportFactory;
use Symfony\Component\Mailer\Transport\Dsn;
 
/**
 * Ініціалізувати будь-які сервіси застосунку.
 */
public function boot(): void
{
    Mail::extend('brevo', function () {
        return (new BrevoTransportFactory)->create(
            new Dsn(
                'brevo+api',
                'default',
                config('services.brevo.key')
            )
        );
    });
}

Після того як ваш транспорт було зареєстровано, ви можете створити визначення поштовика у файлі конфігурації вашого застосунку config/mail.php, яке використовує новий транспорт:

'brevo' => [
    'transport' => 'brevo',
    // ...
],