Знакомство с Mailables в Laravel 5.3

Статистика: Символов — 6 952/5 767 без пробелов (2 850/2 415 без кода):, слов — 436
Разметка: Wiki
Долгое время отправка писем в Laravel была не очень удобной в сравнении с относительно простым API большинства других функций Laravel. Вот пример отправки письма из документации Laravel 5.2:

%%
Mail::send('emails.reminder', ['user' => $user], function ($m) use ($user) {
    $m->from('hello@app.com', 'Ваше приложение');

    $m->to($user->email, $user->name)->subject('Ваше напоминание!');
});
%%

{{CUT}}

Я не говорю, что она //ужасна//, она намного проще своих конкурентов, но зачастую трудно понять, что происходит в замыкании, а что не происходит, в каком порядке идут параметры и т.д.

== Знакомство с Mailables ==
Mailables - PHP-классы в Laravel 5.3, каждый из которых отвечает за одно письмо: "NewUserWelcome" (приветствие нового пользователя) или "PaymentReceipt" (квитанция об оплате). Появился простой синтаксис "отправки", похожий на управление событиями и задачами, в который вы будете передавать экземпляр нужного вам класса, в данном случае это письмо.

Итак, теперь та же самая отправка письма выглядит так:
%%
Mail::to($user)->send(new Reminder);
%%

Давайте посмотрим на класс %%Reminder%%. Сначала создадим его Artisan-командой:
%%(sh)
php artisan make:mail Reminder
%%

Теперь он находится в папке %%(t)app/Mail%%. Посмотрим, как он выглядит изначально:
%%
<?php

namespace App\Mail;

use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Queue\SerializesModels;

class Reminder extends Mailable
{
    use Queueable, SerializesModels;

    /**
     * Создать новый экземпляр сообщения.
     *
     * @return void
     */
    public function __construct()
    {
        //
    }

    /**
     * Собрать сообщение.
     *
     * @return $this
     */
    public function build()
    {
        return $this->view('view.name');
    }
}
%%

Все те настройки, которые вы делали в замыканиях, теперь находятся в методе %%build()%%. Итак, давайте пересоберём это письмо снова:
%%
public function build()
{
    return $this->from('hello@app.com', 'Ваше приложение')
        ->subject('Ваше напоминание!')
        ->view('emails.reminder');
}
%%

.(alert)
Если вы не задали тему письма, Laravel подставит её, исходя из имени класса. Если класс называется "ApplicationReminder", в теме письма будет "Application Reminder".

=== Передача данных ===
А если мы хотим передать данные в тему письма или в представление? Это происходит в конструкторе:
%%
Mail::to($user)->send(new Reminder($event));
%%

%%
class Reminder extends Mailable
{
    public $event;

    public function __construct($event)
    {
        $this->event = $event;
    }

    public function build()
    {
        return $this->from('hello@app.com', 'Ваше приложение')
            ->subject('Напоминание о событии: ' . $this->event->name)
            ->view('emails.reminder');
    }
}
%%

Все "открытые" свойства нашего "посылаемого" (mailable) класса будут доступны в представлении, поэтому мы можем использовать %%$event%% в представлении:
%%
// resources/views/emails/reminder.blade.php
<h1>{{ $event->name }} уже скоро!</h1>
<p>Lorem ipsum.</p>
%%

А если вы захотите указать данные явно? Это можно сделать, передав массив в вызов %%with()%% в методе %%build()%%:
%%
public function build()
{
    return $this->from('hello@app.com', 'Ваше приложение')
        ->subject('Напоминание о событии: ' . $this->event->name)
        ->view('emails.reminder')
        ->with(['title' => $this->event->name]);
}
%%

=== Настройка списка рассылки ===
Как видите, настройка самого письма происходит в методе %%build()%%, а настройка адресатов происходит при вызове письма. Давайте посмотрим на %%cc%% и %%bcc%%:
%%
Mail::to(User::find(1))
    ->cc(User::find(2))
    ->bcc(User::find(3))
    ->send(new Reminder);

// Эти методы также принимают коллекции
Mail::to(Users::all())
    ->send(new Reminder);
%%

=== Текстовые представления ===
Есть новый метод %%text()%%, идущий в паре с новым методом %%view()%%. Вы можете передать в него представление для текстовой версии этого письма:
%%
public function build()
{
    return $this->view('emails.reminder')
        ->text('emails.reminder_plain');
}
%%

=== Очереди ===
Одна из проблем рассылки писем при выполнении вашего приложения - отправка может занимать несколько секунд. Идеальное решение - постановка в очередь. Это было просто и с предыдущим синтаксисом работы с письмами, и осталось простым с новым: просто выполните %%Mail::queue%% вместо %%Mail::send%%.
%%
Mail::to($user)->queue(new Reminder);
%%

Чтобы указать точное время для отправки, используйте %%later%%:
%%
$when = Carbon\Carbon::now()->addMinutes(15);

Mail::to($user)->later($when, new Reminder);
%%

=== Вложения ===
Скоро вы привыкните к этой фразе. Всё, что вы сейчас можете выполнить в почтовых замыканиях, вы можете выполнить и в методе %%build()%%. В том числе %%attach()%%. Первый параметр - путь к файлу, второй необязательный параметр - массив для настройки дополнительной информации о прикреплённом файле.
%%
public function build()
{
    $this->view('emails.reminders')
        ->attach('/path/to/file', [
            'as' => 'name.pdf',
            'mime' => 'application/pdf',
        ]);
}
%%

Для вложения "сырых" данных используйте %%attachRaw()%%:
%%
public function build()
{
  $this->view('emails.reminders')
      ->attachRaw($this->pdf, 'name.pdf', [
          'mime' => 'application/pdf',
      ]);
}
%%

== Заключение ==
Mailables не является принципиально новой функцией. В ней нет ничего такого, что вы не могли сделать в Laravel раньше.

Но это одна из тех возможностей, которые делают работу с ним приятной. В своих приложениях я постоянно использую отправку писем. И я очень рад этой новой системе. Она определённо полезна.

Подробнее об этой системе вы можете прочитать в ((https://laravel.com/docs/master/mail документации)).