Russian (Pусский) translation by Ilya Nikov (you can also view the original English article)
В этой статье мы рассмотрим API почты в веб-фреймворке Laravel. Laravel использует популярную библиотеку SwiftMailer, которая проста в использовании и поставляется с различными драйверами электронной почты на выбор. На последних этапах статьи мы подробно рассмотрим концепции, рассмотренные в первой половине статьи.
Настройка предварительных условий
Laravel реализует обертку поверх библиотеки SwiftMailer, которая упрощает настройку и использование электронной почты в одно и то же время. Настройки почты по умолчанию можно найти в config/mail.php
.
1 |
<?php
|
2 |
|
3 |
return [ |
4 |
|
5 |
/*
|
6 |
|--------------------------------------------------------------------------
|
7 |
| Mail Driver
|
8 |
|--------------------------------------------------------------------------
|
9 |
|
|
10 |
| Laravel supports both SMTP and PHP's "mail" function as drivers for the
|
11 |
| sending of e-mail. You may specify which one you're using throughout
|
12 |
| your application here. By default, Laravel is setup for SMTP mail.
|
13 |
|
|
14 |
| Supported: "smtp", "sendmail", "mailgun", "mandrill", "ses",
|
15 |
| "sparkpost", "log", "array"
|
16 |
|
|
17 |
*/
|
18 |
|
19 |
'driver' => env('MAIL_DRIVER', 'sendmail'), |
20 |
|
21 |
/*
|
22 |
|--------------------------------------------------------------------------
|
23 |
| SMTP Host Address
|
24 |
|--------------------------------------------------------------------------
|
25 |
|
|
26 |
| Here you may provide the host address of the SMTP server used by your
|
27 |
| applications. A default option is provided that is compatible with
|
28 |
| the Mailgun mail service which will provide reliable deliveries.
|
29 |
|
|
30 |
*/
|
31 |
|
32 |
'host' => env('MAIL_HOST', 'smtp.mailgun.org'), |
33 |
|
34 |
/*
|
35 |
|--------------------------------------------------------------------------
|
36 |
| SMTP Host Port
|
37 |
|--------------------------------------------------------------------------
|
38 |
|
|
39 |
| This is the SMTP port used by your application to deliver e-mails to
|
40 |
| users of the application. Like the host we have set this value to
|
41 |
| stay compatible with the Mailgun e-mail application by default.
|
42 |
|
|
43 |
*/
|
44 |
|
45 |
'port' => env('MAIL_PORT', 587), |
46 |
|
47 |
/*
|
48 |
|--------------------------------------------------------------------------
|
49 |
| Global "From" Address
|
50 |
|--------------------------------------------------------------------------
|
51 |
|
|
52 |
| You may wish for all e-mails sent by your application to be sent from
|
53 |
| the same address. Here, you may specify a name and address that is
|
54 |
| used globally for all e-mails that are sent by your application.
|
55 |
|
|
56 |
*/
|
57 |
|
58 |
'from' => [ |
59 |
'address' => env('MAIL_FROM_ADDRESS', 'hello@example.com'), |
60 |
'name' => env('MAIL_FROM_NAME', 'Example'), |
61 |
],
|
62 |
|
63 |
/*
|
64 |
|--------------------------------------------------------------------------
|
65 |
| E-Mail Encryption Protocol
|
66 |
|--------------------------------------------------------------------------
|
67 |
|
|
68 |
| Here you may specify the encryption protocol that should be used when
|
69 |
| the application send e-mail messages. A sensible default using the
|
70 |
| transport layer security protocol should provide great security.
|
71 |
|
|
72 |
*/
|
73 |
|
74 |
'encryption' => env('MAIL_ENCRYPTION', 'tls'), |
75 |
|
76 |
/*
|
77 |
|--------------------------------------------------------------------------
|
78 |
| SMTP Server Username
|
79 |
|--------------------------------------------------------------------------
|
80 |
|
|
81 |
| If your SMTP server requires a username for authentication, you should
|
82 |
| set it here. This will get used to authenticate with your server on
|
83 |
| connection. You may also set the "password" value below this one.
|
84 |
|
|
85 |
*/
|
86 |
|
87 |
'username' => env('MAIL_USERNAME'), |
88 |
|
89 |
'password' => env('MAIL_PASSWORD'), |
90 |
|
91 |
/*
|
92 |
|--------------------------------------------------------------------------
|
93 |
| Sendmail System Path
|
94 |
|--------------------------------------------------------------------------
|
95 |
|
|
96 |
| When using the "sendmail" driver to send e-mails, we will need to know
|
97 |
| the path to where Sendmail lives on this server. A default path has
|
98 |
| been provided here, which will work well on most of your systems.
|
99 |
|
|
100 |
*/
|
101 |
|
102 |
'sendmail' => '/usr/sbin/sendmail -bs', |
103 |
|
104 |
/*
|
105 |
|--------------------------------------------------------------------------
|
106 |
| Markdown Mail Settings
|
107 |
|--------------------------------------------------------------------------
|
108 |
|
|
109 |
| If you are using Markdown based email rendering, you may configure your
|
110 |
| theme and component paths here, allowing you to customize the design
|
111 |
| of the emails. Or, you may simply stick with the Laravel defaults!
|
112 |
|
|
113 |
*/
|
114 |
|
115 |
'markdown' => [ |
116 |
'theme' => 'default', |
117 |
|
118 |
'paths' => [ |
119 |
resource_path('views/vendor/mail'), |
120 |
],
|
121 |
],
|
122 |
|
123 |
];
|
Когда дело доходит до отправки писем, Laravel поддерживает различные драйверы на выбор. Как вы можете видеть, для MAIL_DRIVER
по умолчанию установлено значение smtp
.
Если вы собираетесь использовать драйвер smtp
для отправки писем, вам также необходимо установить другие связанные параметры, такие как MAIL_HOST
, MAIL_PORT
, MAIL_ENCRYPTION
, MAIL_USERNAME
и MAIL_PASSWORD
.
С другой стороны, если вы собираетесь использовать драйвер sendmail
, то вы хотите убедиться, что системный путь sendmail
установлен в правильное значение в файле config/mail.php
.
Вы также можете установить адрес from
, который будет использоваться при отправке писем под ключом from
. И, наконец, если вы хотите использовать рендеринг электронной почты Markdown, вы можете установить эти параметры под ключом markdown
.
Вишенка на торте - это то, что вы также можете использовать сторонние поставщики почтовых услуг, такие как Mailgun, Mandrill, SES и SparkPost. Если вы используете одну из этих служб, вам нужно убедиться, что вы установили соответствующие параметры в файле config/services.php
.
Таким образом, это было базовое введение в настройки API, связанные с почтой в Laravel. В следующем разделе мы перейдем к пользовательскому примеру, который покажет вам, как отправлять электронные письма.
Создание класса Mailable
В этом разделе мы создадим класс Mailable, который будет использоваться для отправки электронных писем. Класс Mailable отвечает за отправку писем с помощью почтовой программы, настроенной в файле config/mail.php
. Фактически, Laravel уже предоставляет команду artisan, которая позволяет нам создать базовый шаблон.
1 |
php artisan make:mail DemoEmail |
Это должно создать пустой шаблон электронной почты в файле app/Mail/DemoEmail.php
, как показано в следующем фрагменте.
1 |
<?php
|
2 |
|
3 |
namespace App\Mail; |
4 |
|
5 |
use Illuminate\Bus\Queueable; |
6 |
use Illuminate\Mail\Mailable; |
7 |
use Illuminate\Queue\SerializesModels; |
8 |
use Illuminate\Contracts\Queue\ShouldQueue; |
9 |
|
10 |
class DemoEmail extends Mailable |
11 |
{
|
12 |
use Queueable, SerializesModels; |
13 |
|
14 |
/**
|
15 |
* Create a new message instance.
|
16 |
*
|
17 |
* @return void
|
18 |
*/
|
19 |
public function __construct() |
20 |
{
|
21 |
//
|
22 |
}
|
23 |
|
24 |
/**
|
25 |
* Build the message.
|
26 |
*
|
27 |
* @return $this
|
28 |
*/
|
29 |
public function build() |
30 |
{
|
31 |
return $this->view('view.name'); |
32 |
}
|
33 |
}
|
Давайте заменим содержимое этого файла следующим.
1 |
<?php
|
2 |
|
3 |
namespace App\Mail; |
4 |
|
5 |
use Illuminate\Bus\Queueable; |
6 |
use Illuminate\Mail\Mailable; |
7 |
use Illuminate\Queue\SerializesModels; |
8 |
use Illuminate\Contracts\Queue\ShouldQueue; |
9 |
|
10 |
class DemoEmail extends Mailable |
11 |
{
|
12 |
use Queueable, SerializesModels; |
13 |
|
14 |
/**
|
15 |
* The demo object instance.
|
16 |
*
|
17 |
* @var Demo
|
18 |
*/
|
19 |
public $demo; |
20 |
|
21 |
/**
|
22 |
* Create a new message instance.
|
23 |
*
|
24 |
* @return void
|
25 |
*/
|
26 |
public function __construct($demo) |
27 |
{
|
28 |
$this->demo = $demo; |
29 |
}
|
30 |
|
31 |
/**
|
32 |
* Build the message.
|
33 |
*
|
34 |
* @return $this
|
35 |
*/
|
36 |
public function build() |
37 |
{
|
38 |
return $this->from('sender@example.com') |
39 |
->view('mails.demo') |
40 |
->text('mails.demo_plain') |
41 |
->with( |
42 |
[
|
43 |
'testVarOne' => '1', |
44 |
'testVarTwo' => '2', |
45 |
])
|
46 |
->attach(public_path('/images').'/demo.jpg', [ |
47 |
'as' => 'demo.jpg', |
48 |
'mime' => 'image/jpeg', |
49 |
]);
|
50 |
}
|
51 |
}
|
Существует два важных метода, которые класс mailable обычно реализует - __construct
и build
. Метод __construct
используется для инициализации объектов, которые предполагается использовать в шаблоне электронной почты. С другой стороны, метод build
используется для инициализации дополнительных значений, связанных с электронной почтой, таких как, шаблон просмотра, вложения и т.д.
В нашем случае мы передали объект $demo
в качестве аргумента конструктора и присвоили его публичному свойству demo
.
В методе build
мы инициализировали конфигурацию, специфичную для электронной почты.
- Параметр
from
используется для установки адреса электронной почты, который будет использоваться как адрес. - Используя метод
view
, вы можете установить шаблон электронной почты, который будет использоваться при отправке электронной почты с использованием этого mallable. В нашем случае мы установили его вmails.demo
, а это значит, что вам нужно создать файл шаблона представления вresources/views/mails/demo.blade.php
. - Затем метод
text
используется для настройки текстовой версии шаблона электронной почты. - Как мы только что обсуждали, метод
__construct
используется для настройки объектов, которые будут использоваться в шаблоне электронной почты, вы также можете использовать методwith
, который позволяет вам устанавливать данные представления сообщения. - Затем мы использовали метод
attach
для прикрепления изображения с сообщением.
Конечно, нам нужно создать шаблоны писем, которые мы должны использовать при отправке писем. Идем дальше и создаем файл resources/views/mails/demo.blade.php
, такой как показано в следующем фрагменте.
1 |
Hello <i>{{ $demo->receiver }}</i>, |
2 |
<p>This is a demo email for testing purposes! Also, it's the HTML version.</p> |
3 |
|
4 |
<p><u>Demo object values:</u></p> |
5 |
|
6 |
<div> |
7 |
<p><b>Demo One:</b> {{ $demo->demo_one }}</p> |
8 |
<p><b>Demo Two:</b> {{ $demo->demo_two }}</p> |
9 |
</div> |
10 |
|
11 |
<p><u>Values passed by With method:</u></p> |
12 |
|
13 |
<div> |
14 |
<p><b>testVarOne:</b> {{ $testVarOne }}</p> |
15 |
<p><b>testVarTwo:</b> {{ $testVarTwo }}</p> |
16 |
</div> |
17 |
|
18 |
Thank You, |
19 |
<br/> |
20 |
<i>{{ $demo->sender }}</i> |
Кроме того, давайте создадим текстовую версию этого файла в resources/views/mails/demo_plain.blade.php
.
1 |
Hello {{ $demo->receiver }}, |
2 |
This is a demo email for testing purposes! Also, it's the HTML version. |
3 |
|
4 |
Demo object values: |
5 |
|
6 |
Demo One: {{ $demo->demo_one }} |
7 |
Demo Two: {{ $demo->demo_two }} |
8 |
|
9 |
Values passed by With method: |
10 |
|
11 |
testVarOne: {{ $testVarOne }} |
12 |
testVarOne: {{ $testVarOne }} |
13 |
|
14 |
Thank You, |
15 |
{{ $demo->sender }} |
Таким образом, это был класс mailable, доступный для отправки, но мы еще не сделали этого, поскольку нам нужно использовать фасад Mail
для отправки писем. В следующем разделе мы рассмотрим, как вы можете использовать Mail
Facade для отправки электронной почты с использованием класса DemoEmail
Mailable, который был только что создан в этом разделе.
Завершение
В этом разделе мы создадим пример, демонстрирующий, как вы можете использовать класс Mailable
, который был создан в последнем разделе.
Давайте создадим файл контроллера в app/Http/Controllers/MailController.php
со следующим содержимым.
1 |
<?php
|
2 |
namespace App\Http\Controllers; |
3 |
|
4 |
use App\Http\Controllers\Controller; |
5 |
use App\Mail\DemoEmail; |
6 |
use Illuminate\Support\Facades\Mail; |
7 |
|
8 |
class MailController extends Controller |
9 |
{
|
10 |
public function send() |
11 |
{
|
12 |
$objDemo = new \stdClass(); |
13 |
$objDemo->demo_one = 'Demo One Value'; |
14 |
$objDemo->demo_two = 'Demo Two Value'; |
15 |
$objDemo->sender = 'SenderUserName'; |
16 |
$objDemo->receiver = 'ReceiverUserName'; |
17 |
|
18 |
Mail::to("receiver@example.com")->send(new DemoEmail($objDemo)); |
19 |
}
|
20 |
}
|
Важно отметить, что мы включили фасад Illuminate\Support\Facades\Mail
, который будет использоваться для отправки электронной почты. В методе send
следующий оператор отвечает за отправку электронной почты, сначала инициализируя App\Mail\DemoEmail
Mailable.
1 |
Mail::to("receiver@example.com")->send(new DemoEmail($objDemo)); |
Метод to
в фасаде Illuminate\Support\Facades\Mail
возвращает экземпляр класса \Illuminate\Mail\PendingMail
, который уже содержит соответствующую почтовую программу, настроенную в файле config/mail.php
.
И, наконец, мы используем метод send
класса \Illuminate\Mail\PendingMail
, который отправляет фактическое электронное письмо.
Чтобы протестировать его, добавим связанный маршрут в файл routes/web.php
.
1 |
// Email related routes
|
2 |
Route::get('mail/send', 'MailController@send'); |
И с этим вы можете открыть URL http://your-laravel-site.com/mail/send, чтобы узнать, работает ли он так, как ожидалось.
С другой стороны, если вы хотите быстро протестировать свои шаблоны электронной почты, не отправляя фактические электронные письма, в Laravel есть положение, позволяющее регистрировать все исходящие письма.
Для этого вам нужно установить значение MAIL_DRIVER
в log
в файле config/mail.php
. Затем вы можете запустить вышеупомянутый URL-адрес и проверить файл журнала, чтобы проверить, был ли там зарегистрирован шаблон электронной почты.
Если все будет хорошо, вы должны увидеть, что электронное письмо регистрируется в файле storage/logs/laravel.lo
g.
В значительной степени это касается функции почты в Laravel, и это завершает эту статью.
Заключение
Сегодня мы изучили почтовый API, который встроен в Laravel.
Начиная с базовых концепций, мы реализовали класс mailable который является важным элементом в API почты в Laravel. В конце мы также протестировали класс mailable, создав пользовательский контроллер, чтобы увидеть, действительно ли он работает.
Если вы только начинаете работу с Laravel или хотите расширить свои знания, создать свой сайт или приложение, у нас есть множество уроков и статей, которые вы можете изучать на Envato Market.
Я хотел бы узнать ваши отзывы в форме вопросов и комментариев, используя приведенный ниже канал!