() translation by (you can also view the original English article)
سنتعرّف في هذا المقال على الواجهة البرمجية الخاصة بالرسائل اﻹلكترونية والتي يقدّمها إطار الويب 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 |
];
|
124 |
يدعم Laravel العديد من محركات إرسال الرسائل اﻹلكترونية، وكما هو واضح فإنّ المحرّك الافتراضي MAIL_DRIVER
يأخذ القيمة smtp
.
إن كنت ترغب في استخدام محرك smtp
ﻹرسال الرسائل اﻹلكترونية فيجب عليك حينئذ أن تضبط بعض اﻹعدادات المرتبطة بهذا المحرك مثل MAIL_HOST
و MAIL_PORT
و MAIL_ENCRYPTION
و MAIL_USERNAME
و MAIL_PASSWORD
.
من جانب آخر، إن كنت ترغب في استخدام محرّك sendmail
فعليك أن تحرص على إدخال القيمة الصحيحة لمسار النظام الخاص بالمحرّك sendmail
في ملف config/mail.php
.
يمكنك أيضًا أن تعين قيمة عنوان المرسِل from
والذي سيُستخدم أثناء عملية إرسال الرسائل اﻹلكترونية تحت المفتاح from
. وأخيرًا، إن كنت ترغب في استخدام صيغة مارك داون لكتابة الرسائل اﻹلكترونية، فيمكن ضبط اﻹعدادات في المفتاح markdown
.
إضافة إلى كل ما سبق، يمكنك استخدام مزوّد خدمة خارجي مثل Mailgun، و Mandrill و SES و SparkPost. إن كنت ترغب في استخدام إحدى هذه الموّدات فيجب عليك إضافة اﻹعدادات الخاصّة بها ضمن الملف config/services.php
.
كانت هذه مقدّمة مختصرة عن الإعدادات الخاصّة بالواجهة البرمجية لإرسال الرسائل اﻹلكترونية في Laravel. سنعرض في القسم التالي من المقال وما بعده مثالًا نبيّن فيه طريقة إرسال الرسائل الإلكترونية.
إنشاء صنف 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 |
}
|
هناك تابعان مهمّان جدًّا في هذا الصنف، وهما __construct
و build
. يستخدم التابع __construct
في استبداء initialize الكائنات التي ترغب في استخدامها في قالب البريد اﻹلكتروني. أما التابع build
فيستخدم لاستبداء بعض القيم الخاصّة بالبريد اﻹلكتروني مثل from، view template، attachments وما شابهها.
وفي حالتنا هذه، مرّرنا الكائن $demo
كمعامل بانٍ، وأسندناه إلى الخاصّية العامة demo
.
وقمنا كذلك باستبداء إحدى الإعدادات الخاصّة بالبريد اﻹلكتروني في التابع build
.
- يُستخدم التابع
form
لتعيين عنوان بريد اﻹلكتروني الخاص بالمرسِل. - يمكن تعيين القالب المستخدم في الرسالة اﻹلكترونية المرسلة بواسطة التابع
view
، وفي حالتنا هذه استخدمنا القيمة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
وسنتعرّف على طريق إرسال الرسائل اﻹلكترونية باستخدام صنف mailable الذي يحمل الاسم DemoEmail
والذي أنشأناه في هذه القسم.
جمع اﻷجزاء بعضها ببعض
سننشئ في هذا القسم مثالًا نوضّح من خلاله كيفية استخدام الصنف 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
أوّلًا.
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'); |
يمكنك الآن التوجّه إلى العنوان http://your-laravel-site.com/mail/send للتأكد من أن كل شيء يعمل بصورة جيدة.
إن كنت ترغب في اختبار قوالب البريد اﻹلكتروني الخاصة بك بصورة سريعة، دون إرسال رسائل إلكترونية حقيقية، فإنّ Laravel يقدّم طريقة تسمح بتسجيل جميع الرسائل المرسلة.
وللقيام بذلك سنحتاج إلى ضبط قيمة Mail_DRIVER
إلى log
ضمن ملف config/mail.php
. ويمكنك بعد ذلك التوجّه إلى الرابط السابق ثم تفحّص السجلات للتأكد من أنّه قد تمّ بالفعل تسجيل قالب الرسالة اﻹلكترونية.
إن جرى كل شيء على ما يرام، سترى رسالة إلكترونية مسجّلة في ملف السجل storage/logs/laravel.log
.
وهكذا نكون قد تطرّقنا إلى كل ما يهمّنا بخصوص إرسال الرسائل اﻹلكترونية في Laravel، وبهذا نكون قد أنهينا المقال أيضًا.
ختامًا
تعرّفنا في هذا المقال على الواجهة البرمجية الداخلية الخاصّة بإرسال الرسائل اﻹلكترونية في إطار الويب Laravel والذي يدعم مجموعة واسعة من محرّكات اﻹرسال أيضًا.
تعرّفنا في البداية إلى بعض المفاهيم الأساسية، ثم استخدمنا صنف mailable والذي يعدّ العنصر اﻷساسي في الواجهة البرمجية الخاصة بإرسال الرسائل اﻹلكترونية في Laravel. وفي النهاية، أجرينا اختبارًا لصنف mailable وذلك بإنشاء متحكّم خاص يساعدنا على مشاهدة طريقة عمل هذا الصنف.
إن كنت تخطو خطواتك اﻷولى في Laravel أو كنت ترغب في زيادة معلوماتك، أو تحسين تطبيقك أو موقعك اﻹلكتروني، فهناك الكثير من المواد والملحقات التي يمكنك الاستفادة منها في سوق Envato.
يسعدني الاطلاع على آرائكم واﻹجابة عن أسئلتكم في التعليقات.