ارسال ایمیل در لاراول (Laravel) – راهنمای کاربردی
فریمورک وب لاراول از مزیت کتابخانه محبوب SwiftMailer برخوردار است که استفاده از آن آسان است و طیف متنوعی از درایورهای ایمیل ارائه کرده است. در همین راستا، در این مقاله قصد داریم به بررسی API ارسال ایمیل در لاراول بپردازیم.
راهاندازی پیشنیازها
لاراول یک کتابخانه پوششی بر روی کتابخانه SwiftMailer بنا میکند که مدیریت ایمیل را همزمان به کاری بسیار آسان و قابل پیکربندی تبدیل میکند.
تنظیمات پیشفرض ایمیل را میتوانید در فایل config/mail.php مشاهده کنید:
1<?php
2
3return [
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];
هنگامی که از ارسال ایمیل صحبت میکنیم، لاراول از درایورهای مختلفی پشتیبانی میکند. چنان که میبینید MAIL_DRIVER پیشفرض به صورت stmp تنظیم شده است. اگر قصد دارید از درایور stmp برای ارسال ایمیل استفاده کنید، در این صورت به مجموع تنظیمات دیگری مانند 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 ایمیل در لاراول داشتیم. از این بخش به بعد قصد داریم یک مثال سفارشی را بررسی کنیم که روش ارسال ایمیلها را نمایش میدهد.
ایجاد کلاس Mailable
در این بخش، کلاس Mailable را میسازیم که برای ارسال ایمیل استفاده میشوند.
کلاس Mailable مسئول ارسال ایمیلها با استفاده از mailer است که آن نیز در فایل config/mail.php پیکربندی شده است. در واقع لاراول از قبل یک دستور آرتیزان به صورت زیر دارد که امکان ایجاد یک قالب پایه را به ما میدهد:
1php artisan make:mail DemoEmail
این دستور یک قالب ایمیل خالی در آدرس app/Mail/DemoEmail.php ایجاد میکند که در قطعه کد زیر میتوانید آن را ببینید:
1<?php
2
3namespace App\Mail;
4
5use Illuminate\Bus\Queueable;
6use Illuminate\Mail\Mailable;
7use Illuminate\Queue\SerializesModels;
8use Illuminate\Contracts\Queue\ShouldQueue;
9
10class 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
3namespace App\Mail;
4
5use Illuminate\Bus\Queueable;
6use Illuminate\Mail\Mailable;
7use Illuminate\Queue\SerializesModels;
8use Illuminate\Contracts\Queue\ShouldQueue;
9
10class 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 برای مقداردهی مقادیر خاص ایمیل مانند from، قالب view، پیوست ایمیل و نظایر آن استفاده میشود.
در این مورد، شیء demo$ را به صورت یک آرگومان سازنده ارسال میکنیم و آن را به مشخصه عمومی demo انتساب میدهیم. در متد build یک پیکربندی بندی خاص ایمیل را مقداردهی میکنیم.
From برای تعیین آدرس ایمیلی استفاده میشود که در آدرس فرستنده ایمیل درج خواهد شد.
با استفاده از متد view میتوان قالب ایمیلی را تعیین کرد که در زمان ارسال کردن ایمیل با استفاده از کلاس mailable استفاده خواهد شد. در این مورد ما از mails.demo استفاده میکنیم و معنی آن این است که باید یک فایل قالب view در مسیر resources/views/mails/demo.blade.php بسازید.
سپس متد text برای راهاندازی نسخه متنی سادهای از یک قالب ایمیل استفاده خواهد شد.
چنان که قبلاً اشاره کردیم متد construct__ برای راهاندازی شیءهایی استفاده میشود که در قالب ایمیل استفاده میشوند. میتوان از متد with نیز استفاده کرد که امکان تنظیم دادههای view یک پیام را فراهم میسازند. سپس از متد attach برای الصاق یک تصویر به پیام استفاده میکنیم.
البته ما باید یک قالب ایمیل ایجاد کنیم که در زمان ارسال ایمیلها مورد استفاده قرار خواهد گرفت. در ادامه فایل resources/views/mails/demo.blade.php را با محتوای زیر ایجاد میکنیم:
1Hello <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
18Thank You,
19<br/>
20<i>{{ $demo->sender }}</i>
همچنین یک نسخه متنی ساده از این فایل را در مسیر resources/views/mails/demo_plain.blade.php میسازیم:
1Hello {{ $demo->receiver }},
2This is a demo email for testing purposes! Also, it's the HTML version.
3
4Demo object values:
5
6Demo One: {{ $demo->demo_one }}
7Demo Two: {{ $demo->demo_two }}
8
9Values passed by With method:
10
11testVarOne: {{ $testVarOne }}
12testVarOne: {{ $testVarOne }}
13
14Thank You,
15{{ $demo->sender }}
بدین ترتیب کلاس mailable بنا به دلخواه ما تنظیم شده است، اما هنوز کار ما تمام نشده است، چون باید از یک facade به نام Mail برای ارسال عملی ایمیلها استفاده کنیم. در بخش بعدی در مورد شیوه استفاده از facade به نام Mail برای ارسال ایمیل با استفاده از DemoEmail در کلاس mailable که هم اینک ایجاد کردیم توضیح خواهیم داد.
جمعبندی
در این بخش یک نمونه میسازیم که نشان میدهد چگونه میتوان از کلاس mailable ایجاد شده در مرحله قبلی استفاده کرد.
یک فایل کنترلر در مسیر app/Http/Controllers/MailController.php با محتوای زیر میسازیم:
1<?php
2namespace App\Http\Controllers;
3
4use App\Http\Controllers\Controller;
5use App\Mail\DemoEmail;
6use Illuminate\Support\Facades\Mail;
7
8class 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}
لازم به اشاره است که ما Facede موجود در مسیر Illuminate\Support\Facades\Mail که برای ارسال ایمیل استفاده میشود را نیز در این فایل include کردهایم. در متد send گزاره زیر مسئول ارسال یک ایمیل با مقداردهی App\Mail\DemoEmail در کلاس Mailable است:
1Mail::to("receiver@example.com")->send(new DemoEmail($objDemo));
متد to در Facade به نام Illuminate\Support\Facades\Mail یک وهله از کلاس \Illuminate\Mail\PendingMail بازگشت میدهد که از قبل شامل یک mailer مناسب پیکربندی شده در فایل config/mail.php است.
در نهایت از متد send در کلاس Illuminate\Mail\PendingMail\ استفاده میکنیم که عملاً یک ایمیل را ارسال میکند.
برای تست کردن این پروژه نمونه، یک مسیر مرتبط را در فایل اضافه میکنیم:
1// Email related routes
2Route::get('mail/send'، 'MailController@send');
در این مرحله میتوانید URL زیر را اجرا کنید تا ببینید که مطابق انتظار کار میکند:
1http://your-laravel-site.com/mail/send
از سوی دیگر اگر میخواهید قالبهای ایمیل خود را به سرعت و بدون ارسال واقعی ایمیل تست کنید، شرایطی در لاراول تدارک دیده شده است که امکان لاگ کردن همه ایمیلهای خروجی را میدهد.
برای استفاده از این امکان باید مقدار MAIL_DRIVER را در فایل config/mail.php به log تنظیم کنید. سپس میتوانید URL فوقالذکر را اجرا کرده و فایل لاگ را بررسی کنید و ببینید که آیا قالب ایمیل در آنجا لاگ شده است یا نه.
اگر همه چیز به درستی پیش برود، باید ببینید که یک ایمیل در فایل storage/logs/laravel.log لاگ شده است. این همه آن چیزی است که در مورد قابلیت ایمیل در لاراول میتوان گفت و بدین ترتیب به انتهای این مقاله میرسیم.
سخن پایانی
در این مطلب به معرفی API ایمیل پرداختیم که از قابلیتهای داخلی لاراول است و از گستره متنوعی از درایورهای ارسال ایمیل نیز پشتیبانی میکند. ما کار خود را با توضیح مفاهیم مقدماتی آغاز کردیم و کلاس mailable را پیادهسازی کردیم که یک جزء ضروری در API ایمیل در لاراول است. در انتها کلاس mailable را نیز با ایجاد یک کنترلر سفارشی تست کردیم تا طرز کار عملی آن را مشاهده کنیم.
اگر این مطلب برای شما مفید بوده است، آموزشهای زیر نیز به شما پیشنهاد میشوند:
- مجموعه آموزشهای برنامهنویسی PHP
- آموزش REST API در Laravel (لاراول) با بسته Passport
- مجموعه آموزشهای برنامهنویسی
- انتشار لاراول (Laravel Broadcasting) چگونه کار می کند؟ — راهنمای کاربردی
- زمانبندی وظایف در لاراول (Laravel) — راهنمای مقدماتی
==