Работа с e-mail

Драйвер Mandrill

Для использования драйвера Mandrill установите Guzzle и задайте для параметра driver значение mandrill в конфигурационном файле config/mail.php. Затем проверьте, что в конфигурационном файле config/services.php есть следующие параметры:

'mandrill' => [
  'secret' => 'your-mandrill-key',
],

Драйвер SparkPost

Для использования драйвера SparkPost установите Guzzle и задайте для параметра driver значение sparkpost в конфигурационном файле config/mail.php. Затем проверьте, что в конфигурационном файле config/services.php есть следующие параметры:

'sparkpost' => [
  'secret' => 'your-sparkpost-key',
],

Создание отправляемых объектов

В Laravel каждый отправляемый приложением тип email-сообщения представлен «отправляемым» классом. Эти классы хранятся в папке app/Mail. Если у вас нет такой папки, она будет сгенерирована при создании первого отправляемого класса командой shmake:mail:

shphp artisan make:mail OrderShipped

Написание отправляемых объектов

Все настройки отправляемого класса происходят в методе PHPbuild(). В этом методе вы можете вызывать различные другие методы, такие как PHPfrom(), PHPsubject(), PHPview() и PHPattach(), для настройки содержимого и доставки email-сообщения.

Настройка отправителя

Используя метод PHPfrom()

Сначала давайте рассмотрим настройку отправителя email. Другими словами — от кого будет приходить email. Есть два способа настроить отправителя. Первый — с помощью метода PHPfrom() в методе PHPbuild() вашего отправляемого класса:

/**
 * Создание сообщения.
 *
 * @return $this
 */
public function build()
{
  return $this->from('example@example.com')
              ->view('emails.orders.shipped');
}

Используя глобальный адрес from

Если ваше приложение использует одинаковый адрес отправителя для всех своих email-сообщений, то будет излишне вызывать метод PHPfrom() в каждом генерируемом классе. Вместо этого вы можете указать глобальный адрес from в файле настроек config/mail.php. Этот адрес будет использован тогда, когда в отправляемом классе не указан никакой другой адрес отправителя:

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

Настройка представления

В методе PHPbuild() отправляемого класса вы можете использовать метод PHPview() для указания шаблона для построения содержимого email-сообщения. Поскольку обычно для построения содержимого всех email-сообщений используется Blade-шаблон, вам доступна вся мощь и всё удобство шаблонизатора Blade для создания HTML-кода ваших email-сообщений:

/**
 * Создание сообщения.
 *
 * @return $this
 */
public function build()
{
  return $this->view('emails.orders.shipped');
}

Вы можете создать папку resources/views/emails для размещения всех ваших email-шаблонов, или любую другую папку в каталоге resources/views.

Текстовые email-сообщения

Если вы хотите определить текстовую версию вашего email, используйте метод PHPtext(). Подобно методу PHPview() метод PHPtext() принимает имя шаблона, который будет использован для построения содержимого email-сообщения. Вы можете определить обе версии вашего сообщения — HTML и текстовую:

/**
 * Создание сообщения.
 *
 * @return $this
 */
public function build()
{
  return $this->view('emails.orders.shipped')
              ->text('emails.orders.shipped_plain');
}

Данные представления

Через общедоступные свойства

Обычно необходимо передать какие-либо данные в представление, которые можно использовать при построении HTML-кода email-сообщения. Есть два способа сделать данные доступными для вашего представления. Первый — любое общедоступное (public) свойство, определённое в вашем отправляемом классе, автоматически станет доступным для представления. Например, вы можете передать данные в конструктор вашего отправляемого класса и поместить эти данные в общедоступные свойства, определённые в классе:

<?php

namespace App\Mail;

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

class OrderShipped extends Mailable
{
  use Queueable, SerializesModels;

  /**
   * Экземпляр заказа.
   *
   * @var Order
   */
  public $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>

Через метод PHPwith()

Если вы хотите настроить формат данных вашего email-сообщения до того, как они будут отправлены в шаблон, вы можете вручную передать данные в представление методом PHPwith(). Вы будете по-прежнему передавать данные через конструктор отправляемого класса, но вам надо поместить эти данные в свойства protected или private, чтобы данные не были автоматически доступны шаблону. Затем при вызове метода PHPwith() передайте массив данных, которые должны быть доступны шаблону:

<?php

namespace App\Mail;

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

class OrderShipped extends Mailable
{
  use Queueable, SerializesModels;

  /**
   * Экземпляр заказа.
   *
   * @var Order
   */
  protected $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,
                ]);
  }
}

После передачи данных в метод PHPwith() они автоматически станут доступны для вашего представления, и вы сможете обращаться к ним как к любым другим данным Blade-шаблонах:

<div>
  Price: {{ $orderPrice }}
</div>

Для добавления к письму вложений используйте метод PHPattach() в методе PHPbuild() отправляемого класса. Метод PHPattach() принимает первым аргументом полный путь к файлу:

/**
 * Создание сообщения.
 *
 * @return $this
 */
public function build()
{
  return $this->view('emails.orders.shipped')
              ->attach('/path/to/file');
}

Для добавления к письму вложений служит метод PHPattach() на объекте PHP$message, переданном в ваше замыкание. Метод PHPattach() принимает первым аргументом полный путь к файлу:

Mail::send('emails.welcome', $data, function ($message) {
  //

  $message->attach($pathToFile);
});

Вложение «сырых» данных

Метод PHPattachData() можно использовать для добавления «сырой» строки байтов в качестве вложения. Например, вы можете использовать этот метод, если вы сгенерировали PDF в памяти и хотите прикрепить его к письму, не записывая на диск. Метод PHPattachData() принимает «сырые» данные первым аргументом, имя файла вторым аргументом, и массив параметров третьим аргументом:

/**
 * Создание сообщения.
 *
 * @return $this
 */
public function build()
{
  return $this->view('emails.orders.shipped')
              ->attachData($this->pdf, 'name.pdf', [
                'mime' => 'application/pdf',
              ]);
}

Метод PHPattachData() можно использовать для добавления «сырой» строки байтов в качестве вложения. Например, вы можете использовать этот метод, если вы сгенерировали PDF в памяти и хотите прикрепить его к письму, не записывая на диск:

$message->attachData($pdf, 'invoice.pdf');

$message->attachData($pdf, 'invoice.pdf', ['mime' => $mime]);

Для отправки сообщений используйте метод PHPto() фасада Mail. Метод PHPto() принимает email-адрес, экземпляр пользователя или коллекцию пользователей. Если вы передадите объект или коллекцию объектов, то обработчик почты автоматически использует их свойства email и name для настройки получателей email-сообщения, поэтому эти атрибуты должны быть доступны в ваших объектах. После настройки получателей вы можете передать экземпляр вашего отправляемого класса в метод PHPsend():

<?php

namespace App\Http\Controllers;

use App\Order;
use App\Mail\OrderShipped;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Mail;
use App\Http\Controllers\Controller;

class OrderController extends Controller
{
  /**
   * Доставка данного заказа.
   *
   * @param  Request  $request
   * @param  int  $orderId
   * @return Response
   */
  public function ship(Request $request, $orderId)
  {
    $order = Order::findOrFail($orderId);

    // Доставка заказа...

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

Само собой при отправке сообщений вы можете указать не только получателей to. Вы можете задать получателей to, cc и bcc одним сцепленным вызовом метода:

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

Laravel позволяет хранить почтовые сообщения в представлениях. Например, вы можете расположить свои сообщения в папке emails, создав её в папке resources/views.

Для отправки сообщения используется метод PHPsend() фасада Mail. Этот метод принимает три аргумента. Первый — имя представления, которое содержит текст сообщения. Второй — массив данных, передаваемых в представление. Третий — функция-замыкание, получающая экземпляр сообщения, и позволяющая вам настроить различные параметры сообщения, такие как получатели, тема и т.д.:

<?php

namespace App\Http\Controllers;

use Mail;
use App\User;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller;

class UserController extends Controller
{
  /**
   * Отправка пользователю напоминания по e-mail.
   *
   * @param  Request  $request
   * @param  int  $id
   * @return Response
   */
  public function sendEmailReminder(Request $request, $id)
  {
    $user = User::findOrFail($id);

    Mail::send('emails.reminder', ['user' => $user], function ($m) use ($user) {
      $m->from('hello@app.com', 'Your Application');

      $m->to($user->email, $user->name)->subject('Your Reminder!');
    });
  }
}

Поскольку в этом примере мы передаём массив с ключом user, мы можем отобразить имя пользователя в нашем представлении с помощью такого PHP-кода:

<?php echo $user->name; ?>

Переменная PHP$message всегда передаётся в представления и позволяет вам прикреплять вложения. Поэтому вам не стоит передавать одноимённую переменную с данными для представления.

Построение сообщения

Как уже было сказано, третий аргумент метода PHPsend() — замыкание, которое позволяет указать различные настройки для самого сообщения. С помощью этого замыкания вы можете задать другие атрибуты сообщения, такие как явная рассылка на несколько адресов, скрытая рассылка на несколько адресов, и т.д.:

Mail::send('emails.welcome', $data, function ($message) {
  $message->from('us@example.com', 'Laravel');

  $message->to('foo@example.com')->cc('bar@example.com');
});

Ниже приведён список доступных методов для экземпляра построителя сообщения PHP$message:

$message->from($address, $name = null);
$message->sender($address, $name = null);
$message->to($address, $name = null);
$message->cc($address, $name = null);
$message->bcc($address, $name = null);
$message->replyTo($address, $name = null);
$message->subject($subject);
$message->priority($level);
$message->attach($pathToFile, array $options = []);

// Прикрепить файл из сырой $data string...
$message->attachData($data, $name, array $options = []);

// Получить низкоуровневый экземпляр сообщения SwiftMailer...
$message->getSwiftMessage();

Экземпляр сообщения, передаваемый замыканию метода PHPMail::send(), наследует класс сообщения SwiftMailer, что позволяет вам вызывать любые методы этого класса для создания своего сообщения.

Отправка простого текста

По умолчанию ожидается, что передаваемое в метод PHPsend() представление содержит HTML. Но передавая первым аргументом метода PHPsend() массив, вы можете указать простое текстовое представление вдобавок к HTML-представлению:

Mail::send(['html.view', 'text.view'], $data, $callback);

А если вам надо отправить только простой текст, вы можете указать это при помощи ключа text в массиве:

Mail::send(['text' => 'view'], $data, $callback);

Отправка сырых строк

Если вам надо отправить непосредственно простую строку, используйте метод PHPraw():

Mail::raw('Text to e-mail', function ($message) {
  //
});

Поскольку все генерируемые командой shmake:mail отправляемые классы используют типаж Illuminate\Bus\Queueable, вы можете вызывать методы PHPonQueue() и PHPonConnection() на любом экземпляре отправляемого класса, что позволяет вам указывать название подключения и имя очереди для сообщения:

$message = (new OrderShipped($order))
                ->onConnection('sqs')
                ->onQueue('emails');

Mail::to($request->user())
    ->cc($moreUsers)
    ->bcc($evenMoreUsers)
    ->queue($message);

Помещение в очередь по умолчанию

Если у вас есть отправляемые классы, которые необходимо всегда помещать в очередь, вы можете реализовать контракт ShouldQueue в классе. Тогда даже при вызове метода PHPsend() отправляемый объект будет помещаться в очередь, поскольку он реализует контракт ShouldQueue:

use Illuminate\Contracts\Queue\ShouldQueue;

class OrderShipped extends Mailable implements ShouldQueue
{
  //
}

Если вы хотите поместить сообщение в определённую очередь отправки, то используйте методы PHPqueueOn() и PHPlaterOn():

Mail::queueOn('queue-name', 'emails.welcome', $data, function ($message) {
  //
});

Mail::laterOn('queue-name', 5, 'emails.welcome', $data, function ($message) {
  //
});

Вы можете либо вызывать метод PHPMail::pretend(), либо установить параметр pretend в значение PHPtrue в файле настроек config/mail.php. Когда это сделано, сообщения будут записываться в журнал вашего приложения, вместо отправки получателю.

Laravel генерирует событие непосредственно перед отправкой почтовых сообщений. Учтите, это событие возникает при отправке сообщения, а не при помещении его в очередь. Вы можете зарегистрировать слушатель для этого события в своём EventServiceProvider:

/**
 * Отображения слушателя событий для приложения.
 *
 * @var array
 */
protected $listen = [
  'Illuminate\Mail\Events\MessageSending' => [
    'App\Listeners\LogSentMessage',
  ],
];

Laravel генерирует событие mailer.sending непосредственно перед отправкой почтовых сообщений. Учтите, это событие возникает при отправке сообщения, а не при помещении его в очередь. Вы можете зарегистрировать слушатель события в своём EventServiceProvider:

/**
 * Регистрация всех остальных событий для вашего приложения.
 *
 * @param  \Illuminate\Contracts\Events\Dispatcher  $events
 * @return void
 */
public function boot(DispatcherContract $events)
{
  parent::boot($events);

  $events->listen('mailer.sending', function ($message) {
    //
  });
}