Может войдёшь?
Черновики Написать статью Профиль

Работа с e-mail

перевод документация 5.х

  1. 1. Введение
    1. 1.1. Требования для драйверов
  2. 2. Отправка почты
    1. 2.1. Вложения
    2. 2.2. Строчные вложения
  3. 3. Очереди отправки
  4. 4. Почта и локальная разработка
  5. 5. События
Этот перевод актуален для англоязычной документации на (ветка 5.2) , (ветка 5.1) и (ветка 5.0). Опечатка? Выдели и нажми Ctrl+Enter.

Введение

Laravel предоставляет простой API к популярной библиотеке SwiftMailer. В Laravel есть драйверы для SMTP, Mailgun, Mandrill, SparkPost, Amazon SES, функции PHP mail, и sendmail, поэтому вы можете быстро приступить к рассылке почты с помощью локального или облачного сервиса на ваш выбор.

Требования для драйверов

Драйверы на основе API, такие как Mailgun и Mandrill, зачастую работают проще и быстрее, чем SMTP-сервера.
Для работы таких драйверов необходимо, чтобы в вашем приложении была установлена HTTP-библиотека Guzzle. Вы можете добавить Guzzle в свой проект, добавив такую строку в файл composer.json:

PHP
"guzzlehttp/guzzle""~5.3|~6.0"

Драйвер Mailgun

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

PHP
'mailgun' => [
  
'domain' => 'your-mailgun-domain',
  
'secret' => 'your-mailgun-key',
],

Драйвер Mandrill

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

PHP
'mandrill' => [
  
'secret' => 'your-mandrill-key',
],
+ 5.2

добавлено в 5.2 ()

Драйвер SparkPost

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

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

Драйвер SES
Чтобы использовать драйвер Amazon SES, установите Amazon AWS SDK для PHP. Вы можете установить эту библиотеку, добавив следующую строку в раздел require файла composer.json:

PHP
"aws/aws-sdk-php""~3.0"

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

PHP
'ses' => [
    
'key' => 'your-ses-key',
    
'secret' => 'your-ses-secret',
    
'region' => 'ses-region',  // например, us-east-1
],

Отправка почты

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

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

PHP
<?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
<?php echo $user->name?>

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

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

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

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

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

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

PHP
$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-представлению:

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

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

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

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

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

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

Вложения

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

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

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

При добавлении файлов можно указать их MIME-тип и/или отображаемое имя, передав массив вторым аргументом метода PHPattach() :

PHP
$message->attach($pathToFile, ['as' => $display'mime' => $mime]);
+ 5.2

добавлено в 5.2 ()

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

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

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

Строчные вложения

Вставка изображения в представление сообщения

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

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

Для вставки строчного изображения используйте метод PHPembed() на переменной PHP$message в вашем представлении. Помните, Laravel автоматически делает переменную PHP$message доступной для всех ваших представлений сообщений:

PHP
<body>
  Вот какая-то картинка:

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

Вставка файла из потока данных
Если у вас уже есть строка сырых данных для вставки в почтовое сообщение, вы можете использовать метод PHPembedData() на переменной PHP$message:

PHP
<body>
  А вот картинка, полученная из строки с данными:

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

Очереди отправки

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

Из-за того, что отправка сообщений может сильно повлиять на время обработки запроса, многие разработчики помещают их в очередь на фоновую отправку. Laravel позволяет легко делать это, используя единое API очередей. Для помещения сообщения в очередь просто используйте метод PHPqueue() фасада Mail:

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

Этот метод автоматически позаботится о помещении в очередь задачи для фоновой отправки почтового сообщения. Не забудьте настроить механизм очередей перед использованием данной возможности.

Задержка отправки сообщения

Вы можете задержать отправку сообщения на нужное число секунд методом PHPlater():

PHP
Mail::later(5'emails.welcome'$data, function ($message) {
  
//
});

Помещение сообщения в определённую очередь

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

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

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

Почта и локальная разработка

При разработке приложения обычно предпочтительно отключить доставку отправляемых сообщений. В Laravel есть несколько способов «отключить» реальную отправку почтовых сообщений.

Драйвер Log
Один из вариантов — использовать драйвер почты log при локальной разработке. При этом все сообщения e-mail будут заноситься в ваши журналы и не будут отправляться адресатам. Это полезно в первую очередь для быстрой, локальной отладки и проверки данных. Подробнее о настройке различных окружений для приложения читайте в документации по настройке.

+ 5.0

добавлено в 5.0 ()

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

Универсальный получатель
Другой вариант — задать универсального получателя для всех сообщений от фреймворка. при этом все сообщения, генерируемые вашим приложением, будут отсылаться на заданный адрес, вместо адреса, указанного при отправке сообщения. Это можно сделать с помощью параметра to в файле настроек config/mail.php:

PHP
'to' => [
  
'address' => 'dev@domain.com',
  
'name' => 'Dev Example'
],

Mailtrap

И наконец, вы можете использовать сервис MailTrap и драйвер smtp для отправки ваших почтовых сообщений на фиктивный почтовый ящик, где вы сможете посмотреть их при помощи настоящего почтового клиента. Преимущество этого вариант в том, что вы можете проверить то, как в итоге будут выглядеть ваши почтовые сообщения, при помощи средства для просмотра сообщений Mailtrap.

События

+ 5.2

добавлено в 5.2 ()

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

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

добавлено в 5.1 () 5.0 ()

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

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

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

Комментарии (3)

Levon

Здравствуйте ! У меня один небольшой вопрос. Можно ли средствами Laravel 5 отправить e-mail с помощью сервиса Mandrill, при этом используя шаблоны сервиса Mandrill, а не шаблоны blade?

Буду очень благодарен за помощь.

Sawa4

Блин так и не понял ничего... как это все работает((

olko

поддерживаю комментатора выше

Написать комментарий

Разметка: ? ?

Авторизуйся, чтобы прокомментировать.