Работа с e-mail

Статистика: Символов — 5 966/5 058 без пробелов (3 909/3 360 без кода):, слов — 550
Разметка: Wiki
{{TOC}}

{{DOCVER 4.0=0da300f6445bec5a70d007f503834fce957b065b 16.10.2014 5:19:26, 4.1=efd541a0b218b1c6aafb73f0051c18ed150e3c24 25.05.2014 6:21:03, 4.2=d7b13440c003218ed79e9d508706eca01990122f 4.12.2014 5:01:15}}

== Настройка ==
Laravel предоставляет простой интерфейс к популярной библиотеке ((http://swiftmailer.org/ SwiftMailer)). Главный файл настроек - %%(t)app/config/mail.php%%; он содержит всевозможные параметры, позволяющие вам менять SMTP-сервер, порт, логин, пароль, а также устанавливать глобальный адрес **From** для исходящих сообщений. Вы можете использовать любой SMTP-сервер, либо стандартную функцию PHP ((php:mail)) - для этого установите параметр **driver** в значение %%(t)mail%%. Кроме того, доступен драйвер %%(t)sendmail%%.

%%(DOCNEW 4.2=d7b13440c003218ed79e9d508706eca01990122f 4.12.2014 5:01:15)
=== Драйверы API ===
Также Laravel включает в себя драйверы для HTTP API Mailgun и Mandrill. Эти API часто работают проще и быстрее, чем SMTP-сервера. Для работы обоих драйверов необходимо, чтобы в вашем приложении была установлена HTTP-библиотека Guzzle 4. Вы можете добавить Guzzle 4 в свой проект, добавив такую строку в файл %%(t)composer.json%%:
%%(conf)
  "guzzlehttp/guzzle": "~4.0"
~%%

**Драйвер Mailgun**

Для использования драйвера Mailgun установите для параметра %%(t)driver%% значение %%(t)mailgun%% в конфигурационном файле %%(t)app/config/mail.php%%. Затем создайте конфигурационный файл %%(t)app/config/services.php%%, если такого ещё нет в вашем проекте. Проверьте, что в нём есть следующие параметры:
%%(conf)
  'mailgun' => array(
    'domain' => 'your-mailgun-domain',
    'secret' => 'your-mailgun-key',
  ),
~%%

**Драйвер Mandrill**

Для использования драйвера Mandrill установите для параметра %%(t)driver%% значение %%(t)mandrill%% в конфигурационном файле %%(t)app/config/mail.php%%. Затем создайте конфигурационный файл %%(t)app/config/services.php%%, если такого ещё нет в вашем проекте. Проверьте, что в нём есть следующие параметры:
%%(conf)
  'mandrill' => array(
    'secret' => 'your-mandrill-key',
  ),
~%%

=== Драйвер Log ===
Если параметр %%(t)driver%% в вашем конфигурационном файле %%(t)app/config/mail.php%% имеет значение %%(t)log%%, то все сообщения e-mail будут заноситься в ваши журналы и не будут отправляться адресатам. Это полезно в первую очередь для быстрой, локальной отладки и проверки данных. 
%%

== Основы использования ==
Метод %%Mail::send()%% используется для отправки сообщения:
%%
  Mail::send('emails.welcome', array('key' => 'value'), function($message)
  {
    $message->to('foo@example.com', 'Джон Смит')->subject('Привет!');
  });
%%

Первый параметр - имя ((docs/v4/templates шаблона)), который должен использоваться для текста сообщения. Второй - данные, передаваемые в шаблон, часто это ассоциативный массив, в котором элементы данных доступны через %%$key%%. Третий - функция-замыкание, позволяющая вам настроить новое сообщения.

.(alert)
**Внимание:** переменная %%$message%% всегда передаётся в ваш шаблон и позволяет вам прикреплять вложения. Таким образом, вам не стоит передавать одноимённую переменную с данными для шаблона.

В дополнение к телу сообщения в формате HTML вы можете указать текстовое представление:
%%
  Mail::send(array('html.view', 'text.view'), $data, $callback);
%%

Вы также можете оставить только один формат, передав массив с ключом %%(t)html%% или %%(t)text%%:
%%
  Mail::send(array('text' => 'view'), $data, $callback);
%%

Вы можете указывать другие настройки для сообщения, например, копии или вложения:
%%
  Mail::send('emails.welcome', $data, function ($message) {
    $message->from('us@example.com', 'Laravel');

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

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

При добавлении файлов можно указывать их ((ВП:MIME))-тип и/или отображаемое имя:
%%
  $message->attach($pathToFile, array('as' => $display, 'mime' => $mime));
%%

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

== Добавление строчных вложений ==
Обычно добавление строчных вложений - утомительное занятие, однако Laravel делает его проще, позволяя вам добавлять файлы и получать соответствующие CID.

.(tl_note)
Строчные вложения - файлы, не видимые получателю в списке вложений, но используемые внутри HTML-тела сообщения; CID - уникальный идентификатор внутри данного сообщения, используемый вместо URL в таких атрибутах, как %%(t)src%% - //прим. пер.//

**Добавление картинки в шаблон сообщения**
%%
  <body>
    Вот какая-то картинка:

    <img src="<?php echo $message->embed($pathToFile); ?>">
  </body>
%%

**Добавление файла из потока данных**
%%
  <body>
    А вот картинка, полученная из строки с данными:

    <img src="<?php echo $message->embedData($data, $name); ?>">
  </body>
%%

Переменная **$message** всегда передаётся шаблонам сообщений классом %%Mail%%.

== Очереди отправки ==
**Помещение сообщения в очередь отправки**

Из-за того, что отправка сообщений может сильно повлиять на время обработки запроса многие разработчики помещают их в очередь на отправку. Laravel позволяет делать это, используя ((docs/v4/queues единое API очередей)). Для помещения сообщения в очередь просто используйте метод %%Mail::queue()%%:
%%
  Mail::queue('emails.welcome', $data, function ($message) {
    $message->to('foo@example.com', 'Джон Смит')->subject('Привет!');
  });
%%

Вы можете задержать отправку сообщения на нужное число секунд методом %%later()%%:
%%
  Mail::later(5, 'emails.welcome', $data, function ($message) {
    $message->to('foo@example.com', 'Джон Смит')->subject('Привет!');
  });
%%

Если же вы хотите поместить сообщение в определённую очередь отправки, то используйте методы %%queueOn()%% и %%laterOn()%%:
%%
  Mail::queueOn('queue-name', 'emails.welcome', $data, function ($message) {
    $message->to('foo@example.com', 'Джон Смит')->subject('Привет!');
  });
%%

== Локальная разработка ==
При разработке приложения обычно предпочтительно отключить доставку отправляемых сообщений. Для этого вы можете либо вызывать метод %%Mail::pretend()%%, либо установить параметр **pretend** в значение %%true%% в файле настроек %%(t)app/config/mail.php%%. Когда это сделано, сообщения будут записываться в файл ((docs/v4/errors журнала)) вашего приложения, вместо того, чтобы быть отправленными получателю.

**Включение симуляции отправки**
%%
  Mail::pretend();
%%