التعامل مع البريد الإكتروني

مقدمة

يوفّر Laravel واجهة برمجية (API) سلسة و بسيطة للمكتبة الرائجة SwiftMailer مع مشغّل لكل من SMTP و Mailgun و SparkPost و Amazon SOS وتابع mail ، و sendmail. ممّا يسمح بالبداية في إرسال الرسائل الإكترونية بسرعة عبر خدمات محلية أو سحابية من اختيارك.

المشغّلات اللازمة

تكون المشغّلات المعتمدة على الوسائط مثل Mailgun و SparkPost في العادة أسرع وأسهل في الاستعمال من خوادم SMTP. استعمل أحد هذه المشغّلات إن أمكنك. تَستعمل كل المشغّلات التي تعتمد على الوسائط (API) المكتبة Guzzle التي يمكنك تثبيتها باستعمال منظم الحزم Composer.

composer require guzzlehttp/guzzle

المشغّل Mailgun

لاستخدام المشغّل Mailgun، أولًا ثبّت Guzzle ثمّ غير الخيار driver في ملف الضبط config/mail.php للقيمة mailgun. بعد ذلك، تثبت من أنّ ملف الضبط config/services.php يحتوي الخيار التالي:

'mailgun' => [

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

المشغّل SparkPost

لاستخدام المشغّل SparkPost، أولا ثبّت Guzzle ثمّ غير الخيار driver في ملف الضبط config/mail.php للقيمة sparkpost. بعد ذلك، تثبت من أنّ ملف الضبط config/services.php يحتوي الخيار التالي:

'sparkpost' => [

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

يمكن أيضًا ضبط نقطة نهاية الوسيط التي يجب استعمالها إن احتجت لذلك:

'

sparkpost' => [

   'secret' => 'your-sparkpost-key',
   'options' => [
       'endpoint' => 'https://api.eu.sparkpost.com/api/v1/transmissions',
   ],
],

المشغّل SES

لاستخدام المشغّل Amazon SES يجب أولًا تثبيت Amazon AWS SDK الخاص بلغة PHP. يمكنك تثبيت المكتبة عبر إضافة السطر التالي للقسم require من الملف composer.json:

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

بعد ذلك غير الخيار driver في ملف الضبط config/mail.php إلى القيمة ses. ثمّ تثبت من أنّ ملف الضبط config/services.php يحتوي الخيار التالي:

'ses' => [

   'key' => 'your-ses-key',
   'secret' => 'your-ses-secret',
   'region' => 'ses-region', // e.g. us-east-1
],

إنشاء الأصناف القابلة للإرسال

في Laravel، كل نوع من الرسائل المرسلة من التطبيق تُمَثّل في صنف (class) قابل للإرسال "mailable". تُخزّن هذه الأصناف في المجلد app/Mail. لا تقلق إذا لم تجد المجلد في تطبيقك إذ سيصنع عندما تُنشِئ أول صنف قابل للإرسال باستعمال الأمر make:mail:

php artisan make:mail OrderShipped

كتابة الأصناف القابلة لإرسال

يُضبَط الصنف القابل للإرسال في التابع build. في هذا التابع، يمكنك نداء عدّة عوامل مثل from و subject و view و attach لضبط طريقة التقديم والإرسال.

ضبط المرسل

استعمال التابع from

لنبدأ أولا بضبط المرسِل، أو المكان الذي سيراه متلقي الرسالة كمصدر الإرسال. توجد طريقتان للقيام بهذا. أولًا، يمكنك استعمال التابع from داخل التابع build من الصنف القابل للإرسال:

/**

* بناء الرسالة
*
* @return $this
*/
public function build() {

   return $this->from('example@example.com')
               ->view('emails.orders.shipped');
}

استعمال عنوان عام from

في حالة كان للتطبيق عنوان واحد تُرسَل منه كل الرسائل، قد يصبح من غير المجدي نداء التابع from في كل صنف قابل للإرسال. عوض ذلك، يمكنك تحديد عنوان عام "from" في ملف الضبط config/mail.php. سيَستعمل هذا العنوان في حالة عدم ذكر عنوان خاص بالصنف القابل للإرسال

'from' => ['address' => 'example@example.com', 'name' => 'App Name'],

ضبط الواجهة

في التابع build من الصنف القابل للإرسال، يمكن نداء التابع view لتحديد أي القوالب يجب استعمالها حين إظهار محتوى الرسائل. حيث تستعمل الرسائل في الغالب قوالب Blade لإظهار المحتوى، لك كل قوة وسهولة استخدام المحرك blade لبناء الرسالة:

/**

* بناء الرسالة
*
* @return $this
*/
public function build() {

   return $this->view('emails.orders.shipped');
}

ملاحظة: قد ترغب بإنشاء المجلد resources/views/emails ليحتوي على قوالب الرسائل، لكنك حرّ في أن تضع القوالب في أي مكان تريد في المجلد resources/views.

البريد الإكتروني ذو النص العادي

يمكنك تعريف نص عادي للرسالة باستعمال التابع text. مثل view، يقبل text اسم القالب الذي سيُستعمل لإظهار محتوى الرسالة. أنت حر في الإختيار بين النسخة العادية ونسخة HTML للرسالة:

/**

* بناء الرسالة
*
* @return $this
*/
public function build() {

   return $this->view('emails.orders.shipped')
               ->text('emails.orders.shipped_plain');
}

إظهار البيانات

عبر الخصائص العمومية

تحتاج في العادة لتمرير بعض البيانات للواجهة لاستعمالها حين إظهار الرسالة. هناك طريقتان لتوفير البيانات للواجهة. أولًا، كل خاصية عامة (public property) معَرّفة في الصنف القابل للإرسال تكون تلقائيًا متاحةً في الواجهة. لذا، يمكنك مثلا تمرير بيانات للتابع الباني في الصنف ثم إعطاء هذه البيانات للخاصيات العامة في الصنف:

<?php

namespace App\Mail;

use App\Order; use Illuminate\Bus\Queueable; use Illuminate\Mail\Mailable; use Illuminate\Queue\SerializesModels;

class OrderShipped extends Mailable

{

   use Queueable, SerializesModels;
   /**
    * خاصية الترتيب 
    *
    * @var Order
    */
   public $order;
   /**
    * صناعة نسخة من الرسالة
    *
    * @return void
    */
   public function __construct(Order $order)
   {
       $this->order = $order;
   }
   /**
    *بناء الرسالة
    *
    * @return $this
    */
   public function build()
   {
       return $this->view('emails.orders.shipped');
   }
}

بعد ضبط البيانات، ستكون متاحة للاستعمال في الواجهة ويمكنك الوصول إليها كبقية البيانات في قوالب blade:

<div>
    Price: {{ $order->price }}
</div>

عبر التابع with

يمكنك تمرير البيانات يدويًا للواجهة باستعمال التابع with إذا أردت تخصيص شكل البيانات قبل إرسالها للقالب. في العادة، ستحتاج لتمرير البيانات للتابع الباني للصنف القابل للإرسال، لكن عليك تغيير صفة البيانات إلى protected أو private حتى لا تكون متاحة تلقائيًا للقالب. ثمّ عند نداء التابع with، مرّر مصفوفة البيانات المتاحة للقالب:

<?php namespace App\Mail; use App\Order; use Illuminate\Bus\Queueable; use Illuminate\Mail\Mailable; use Illuminate\Queue\SerializesModels; class OrderShipped extends Mailable {

   use Queueable, SerializesModels;
   /**
    * خاصية الترتيب.
    *
    * @var Order
    */
   protected $order;
   /**
    * صناعة الرسالة.
    *
    * @return void
    */
   public function __construct(Order $order)
   {
       $this->order = $order;
   }
   /**
    *
    * @return $this
    */
   public function build()
   {
       return $this->view('emails.orders.shipped')
                   ->with([
                       'orderName' => $this->order->name,
                       'orderPrice' => $this->order->price,
                   ]);
   }
}

بعد ضبط البيانات، ستكون متاحةً للاستعمال في الواجهة ويمكنك ولوجها كبقية البيانات في قوالب blade

<div>
    Price: {{ $order->price }}
</div>

المرفقات

لإضافة مرفقات للرسالة، يُستعمل التابع attach في التابع build من الصنف. يقبل التابع مسارًا كاملًا للملف كمعامل أول:

/** 
* بناء الرسالة 
* 
* @return $this
*/ 
public function build() 
{ return $this->view('emails.orders.shipped') ->attach('/path/to/file'); }

عند إرفاق ملف مع الرسالة، يمكنك تحديد اسم أو نوع MIME بتمرير مصفوفة كمعامل ثاني للتابع attach:

/**
 * بناء الرسالة.
 * 
 * @return $this
 */
 public function build()
 { return $this->view('emails.orders.shipped') ->attach('/path/to/file', [ 'as' => 'name.pdf', 'mime' => 'application/pdf', ]); }

إرفاق معلومات خام

يمكن استعمال التابع attachData لإرفاق معلومات خام في شكل سلسلة من البيانات الخام. مثلًا، يمكن استعمال هذا التابع لإحداث ملف PDF في الذاكرة و إرفاقها مباشرة بالرسالة دون تسجيلها في القرص الصلب. يقبل التابع attachData بايت (Bytes) من البيانات الخام كمعامل أول. اسم الملف كمعامل ثاني و مصفوفة خيارات كمعامل ثالث:

/** 
* بناء الرسالة. 
* 
* @return $this 
*/ 
public function build()
 { return $this->view('emails.orders.shipped')
 ->attachData($this->pdf, 'name.pdf', [ 'mime' => 'application/pdf', ]); }

المرفقات المُضمّنة

يكون تضمين صور في الرسائل في العادة عملية مرهقة وثقيلة، لكن Laravel يوفّر طريقة سهلة لإرفاق الصور بالرسائل واسترجاع رقم CID الملائم. لتضمين صورة، استعمل التابع embed على المتغيّر message$ في قالب الرسالة. يضيف Laravel تلقائيًا المتغيّر message$ إلى القالب، لذا لا تحتاج لتمريره يدويًا:

<body>

   هنا صورة : 
   <img src="{{ $message->embed($pathToFile) }}">
</body>

تنبيه: المتغير message$ غير موجود في الرسائل المكتوبة بصيغة Markdown.

تضمين مرفقات بيانات خام

إذا كان لديك معلومات بيانات خام تريد تضمينها في قالب الرسالة، يمكنك ذلك باستعمال التابع embedData على المتغيّر message$:

<body>

   هنا صورة من بيانات خام:
   <img src="{{ $message->embedData($data, $name) }}">
</body>

تخصيص رسائل SwiftMailer

يسمح التابع withSwiftMessage من الصنف الأصلي Mailable بتسجيل رد نداء يستدعى مع رسالة SwiftMAiler الخام قبل إرسال الرسالة. مما يعطيك إمكانية تخصيص و تكييف الرسالة قبل إرسالها:

  /**
    *  
    * @return $this
    */
   public function build()
   {
       $this->view('emails.orders.shipped');

       $this->withSwiftMessage(function ($message) {
           $message->getHeaders()
                   ->addTextHeader('Custom-Header', 'HeaderValue');
       });
   }

عناصر القابلة للإرسال Markdown تسمح لك رسائل Markdown باستغلال قوالب و مكوّنات مصنوعة سابقًا في الرسالة. حيث أنّ الرسائل مكتوبة بلغة Markdown، يتمكن Laravel من إظهار قوالب جميلة و متجاوبة للرسالة و صناعة نسخةِ نص عادي في نفس الوقت. إنشاء أصناف Markdown لإنشاء أصناف قابلة للبعث Markdown، يمكن استعمال الخيار markdown-- مع الأمر make:mail: php artisan make:mail OrderShipped --markdown=emails.orders.shipped ثم عند ضبط الصنف في التابع build، استعمل markdown بدل view. يقبل التابع markdown اسم قالب Markdown ومصفوفة اختيارية من البيانات لإتاحتها للقالب: /**

*
* @return $this
*/

public function build() {

   return $this->from('example@example.com')
               ->markdown('emails.orders.shipped');

} كتابة رسائل Markdown تستعمل أصناف Markdown خليطًا من مكوّنات Blade ونص Markdown مما يسمح ببناء الرسالة بسهولة باستعمال المكوّنات الجاهزة: @component('mail::message')

1. Order Shipped

Your order has been shipped!

@component('mail::button', ['url' => $url]) View Order @endcomponent

Thanks,
قالب:config('app.name') @endcomponent ملاحظة: لا تكثر من استعمال الإزاحات فمحلّل اللغة في Markdown سيظهر النص ذا المساحات المُزاحة الكثيرة كنص شيفرة. المكوّن button يُظهر المكوّن button زرَّ ربط في وسط الصفحة. يقبل المكوّن معاملَين: مسار url ولونًا اختياريًا color. الألوان المدعومة هي blue و green و red. يمكنك إضافة أي عدد من الأزرار تريد @component('mail::button', ['url' => $url, 'color' => 'green']) View Order @endcomponent المكوّن panel يُظهر المكوّن Panel النص المُمرّر كمجموعة بخلفية مختلفة قليلًا عن بقية الرسالة مما يسمح بجذب الانتباه لهذا النص: @component('mail::panel') This is the panel content. @endcomponent المكوّن table يسمح المكوّن table بتحويل جدول Markdown لجدول HTML. يقبل المكوّن جدول Markdown كمحتوى ويدعم المحاذاة باستخدام تنسيق Markdown:

@component('mail::table') | Laravel | Table | Example | | ---------------|:-----------------:| ------------:| | Col 2 is | Centered | $10 | | Col 3 is | Right-Aligned| $20 | @endcomponent

تخصيص المكوّنات يمكنك تحميل كل المكونات من Markdown في التطبيق لتخصيصها. لتحويل المكونات، استعمل الأمر vendor:publish لنشر الأصول laravel-mail php artisan vendor:publish --tag=laravel-mail سيُحمّل هذا الأمر مكونات Markdown في المجلد resources/views/vendor/mail. سيحتوي المجلد mail على المجلد html ومجلد markdown، كل منهما يحتوي على النسخة الملائمة من المكوّنات. تُستخدم المكونات في المجلد html لبناء نسخة html من الرسالة في حين تُستخدم المكونات من المجلد Markdown لبناء نسخة نص عادي. لك حرية تخصيص هذه المكونات كما تريد. تخصيص ال CSS بعد تحميل المكونات، يحتوي المجلد resources/views/vendor/mail/html/themes على ملف css المبدئي default.css. يمكنك تخصيص تخطيط CSS في هذا الملف وسيُضمّن تلقائيًا في عرض HTML لرسائل Markdown. ملاحظة : إذا أردت بناء نمط جديد لمكون Markdown، اكتب ملف CSS جديد في المجلد html/themes وغيّر الخيار theme في ملف الضبط mail. إرسال البريد الإلكتروني لإرسال رسالة، استعمل التابع to من الواجهة الثابتة Mail. يقبل التابع to عنوانًا إلكترونيًا، أو نسخة من كائن مستخدم، أو مجموعة مستخدمين. إذا مرّرت كائنًا أو مجموعة كائنات، ستُستخدم الخاصيات mail و name من الكائن عند ضبط متلقي الرسالة. بعد ضبط المتلقي، يمكنك تمرير مثيل من الصنف للتابع send: <?php

namespace App\Http\Controllers;

use App\Order; use App\Mail\OrderShipped; use Illuminate\Http\Request; use Illuminate\Support\Facades\Mail; use App\Http\Controllers\Controller;

class OrderController extends Controller {

   /**
    * Ship the given order.
    *
    * @param  Request  $request
    * @param  int  $orderId
    * @return Response
    */
   public function ship(Request $request, $orderId)
   {
       $order = Order::findOrFail($orderId);

      // Ship order...

       Mail::to($request->user())->send(new OrderShipped($order));
   }

} طبعًا لست محدودًا باستعمال to لضبط المتلقي، يمكنك أيضا ضبط cc و bcc في نداء واحد: Mail::to($request->user())

   ->cc($moreUsers)
   ->bcc($evenMoreUsers)
   ->send(new OrderShipped($order));

عرض الأصناف القابلة للإرسال قد تحتاج في بعض الأحيان لإظهار محتوى صنف قابل للإرسال دون إرساله، للقيام بهذا يمكن استعمال التابع render. يعيد هذا التابع النتيجة الحاصلة من الصنف على شكل سلسلة نصية: $invoice = App\Invoice::find(1);

return (new App\Mail\InvoicePaid($invoice))->render();

معاينة الأصناف في المتصفح عند تصميم قالب صنف قابل للإرسال، من المفيد أن تتمكن من معاينة نتيجة الصنف الممرّرة في المتصفح كأي قالب Blade. لهذا، يسمح Laravel بإعادة أي صنف قابل للإرسال من وحدات التحكم أو مسارات closure. عندما يعاد الصنف، سيُظهَر في المتصفح لمعاينة التصميم بسرعة دون الحاجة لإرسال الرسالة: Route::get('/mailable', function () {

   $invoice = App\Invoice::find(1);

   return new App\Mail\InvoicePaid($invoice);

});

إضافة الرسائل لقائمة الإنتظار إضافة الرسالة حيث يطوّل إرسال البريد الاكتروني وقت إجابة التطبيق، يختار العديد من المطوّرين إضافة الرسائل لقائمة انتظار لإرسالها في خلفية التطبيق. يُتيح Laravel إمكانية القيام هذا بسهولة باستخدام API Unified queue. لإضافة الرسائل لقائمة الانتظار، استعمل التابع queue من الواجهة الثابتة Mail بعد تحديد متلقي الرسالة: Mail::to($request->user())

   ->cc($moreUsers)
   ->bcc($evenMoreUsers)
   ->queue(new OrderShipped($order));

سيتكفّل التابع بدفع مهمّة لقائمة الإنتظار تقوم بإرسال الرسالة في خلفية التطبيق. ستحتاج طبعًا لضبط قوائم الإنتظار قبل استعمال هذه الخاصية. تأخير إضافة الرسالة إذا أردت تأخير إرسال رسالة ما في قائمة الانتظار، استعمل التابع later. يقبل هذا التابع نسخة الكائن DateTime يوضّح وقت الإرسال: $when = now()->addMinutes(10);

Mail::to($request->user())

   ->cc($moreUsers)
   ->bcc($evenMoreUsers)
   ->later($when, new OrderShipped($order));

الإضافة لقائمة انتظار معيّنة حيث أنّ كل الأصناف القابلة للإرسال تُصنع ياستعمال الأمر mail:make لخاصيات Illuminate\Bus\Queueable، يمكن استعمال التابعين onQueue و onConnection على أي نسخة لصنف قابل للإرسال. مما يسمح بتحديد الصلة وقائمة الانتظار لكل رسالة: $message = (new OrderShipped($order))

               ->onConnection('sqs')
               ->onQueue('emails');

Mail::to($request->user())

   ->cc($moreUsers)
   ->bcc($evenMoreUsers)
   ->queue($message);

الإضافة المبدئية إذا كان لديك أصناف قابلة للإرسال تريد أن تضيفها دائمًا لقائمة الانتظار، يمكنك تنفيذ العقد ShouldQueue في الصنف. في هذه الحال، حتى إن ناديت التابع send للإرسال فإنّ الصنف سيضاف للقائمة باعتباره حاملًا للعقد:

use Illuminate\Contracts\Queue\ShouldQueue;

class OrderShipped extends Mailable implements ShouldQueue {

  //

}

الرسائل الإلكترونية والتطوير المحلي عند تطوير تطبيق، قد لا تريد إرسال بريد لعناوين حقيقية. يوفّر Laravel طرائق عديدة لتعطيل عملية الإرسال في مرحلة التطوير. المشغل Log بدل إرسال الرسائل، يكتب المشغل Log محتوى الرسائل في ملف log لمعاينتها. لمزيد من المعلومات حول بيئة التطوير، تفقّد توثيق الضبط. To عام حل آخر يوفره Laravel هو ضبط متلقي عام تُرسل إليه كل الرسائل من التطبيق. بهذه الطريقة، ستُرسل كل الرسائل من التطبيق إلى العنوان محدّد بدل العنوان المذكور كمتلقي للرسالة. يمكن القيام بهذا باستعمال الخيار to في ملف الضبط config/mail.php: 'to' => [

   'address' => 'example@example.com',
   'name' => 'Example'

], Mailtrap في الأخير يمكن استخدام خدمة مثل Mailtrap و المشغل smtp لإرسال الرسائل لعنوان وهمي حيث يمكنك رؤيتها من تطبيق رسائل حقيقي. تسمح هذه الطريقة بمعاينة الرسالة النهائية في قارئ رسائل Mailtrap. الأحداث يطلق Laravel حدثين في عملية الإرسال. يُطلق الحدث MessageSending قبل إرسال الرسالة في حين يُطلق MessageSent بعد البعث. هذه الأحداث تُطلق حين إرسال الرسائل وليس حين إضافتها لقائمة الإنتظار. يمكنك تسجيل مستمعات لهذه الأحداث في الملف ُEventServiceProvider: /**

* المستمعات على الأحداث في التطبيق
*
* @var array
*/

protected $listen = [

   'Illuminate\Mail\Events\MessageSending' => [
       'App\Listeners\LogSendingMessage',
   ],
   'Illuminate\Mail\Events\MessageSent' => [
       'App\Listeners\LogSentMessage',
   ],

];