Symfony/Mailer في PHP: دليل شامل لإرسال البريد الإلكتروني

1. ما هي هذه المكتبة ولماذا تحتاجها

Symfony/Mailer هو مكون قوي ومرن من نظام Symfony البيئي، مصمم لإرسال رسائل البريد الإلكتروني من تطبيقات PHP. على عكس الدالة المدمجة mail() في PHP التي تتطلب ضبط الرؤوس وأنواع MIME يدويًا، يوفر Symfony/Mailer واجهة برمجية كائنية التوجه (OOP) لإنشاء الرسائل وتنسيقها وإرسالها عبر وسائط نقل مختلفة (SMTP، Sendmail، واجهات برمجية لخدمات الطرف الثالث).

المهمة الأساسية لهذه المكتبة هي تجريد عملية إرسال البريد الإلكتروني، مما يسمح للمطور بالتركيز على محتوى الرسالة بدلاً من التفاصيل المنخفضة المستوى للبروتوكولات. يدعم Symfony/Mailer قوالب HTML، المرفقات، تضمين الصور، توقيع DKIM، بالإضافة إلى التكامل مع خدمات البريد الإلكتروني الشهيرة عبر Mailer DSN (مصدر بيانات الاسم).

هذه المكتبة لا غنى عنها في المشاريع التي تتطلب إرسالًا موثوقًا للرسائل المعاملاتية (تأكيد التسجيل، إعادة تعيين كلمة المرور، الإشعارات)، النشرات التسويقية، أو أي إشعارات بريد إلكتروني أخرى. بفضل بنيتها المعيارية، يمكن اختبار Symfony/Mailer بسهولة (عبر MockTransport) وقابلة للتوسع.

2. التثبيت

يتم التثبيت عبر Composer - مدير الحزم القياسي لـ PHP. قم بتنفيذ الأمر التالي في الطرفية داخل مجلد مشروعك:

composer require symfony/mailer

إذا كنت تستخدم Symfony Flex (موصى به)، فسيتم إنشاء ملف الإعدادات config/packages/mailer.yaml تلقائيًا بعد التثبيت. للعمل مع خدمات البريد الإلكتروني الشهيرة (SendGrid، Mailgun، Amazon SES وغيرها)، قم بتثبيت المحول المناسب، على سبيل المثال:

composer require symfony/sendgrid-mailer
composer require symfony/mailgun-mailer
composer require symfony/amazon-mailer

ستحتاج أيضًا إلى مكون symfony/http-client للعمل مع وسائط النقل عبر API:

composer require symfony/http-client

3. البداية السريعة - مثال عملي بسيط

بعد تثبيت المكتبة، يمكنك إرسال أول بريد إلكتروني في بضعة أسطر فقط. قم بإنشاء ملف send_email.php:

<?php
// send_email.php
require_once 'vendor/autoload.php';

use Symfony\Component\Mailer\Mailer;
use Symfony\Component\Mailer\Transport\Smtp\EsmtpTransport;
use Symfony\Component\Mime\Email;

// 1. إنشاء وسيلة النقل (خادم SMTP لجيميل)
$transport = new EsmtpTransport('smtp.gmail.com', 587, true);
$transport->setUsername('your-email@gmail.com');
$transport->setPassword('your-app-password'); // استخدم كلمة مرور التطبيق

// 2. إنشاء Mailer
$mailer = new Mailer($transport);

// 3. إنشاء الرسالة
$email = (new Email())
    ->from('your-email@gmail.com')
    ->to('recipient@example.com')
    ->subject('مرحباً من Symfony Mailer!')
    ->text('هذه رسالة اختبارية تم إرسالها باستخدام Symfony/Mailer.')
    ->html('
مرحباً!
هذه هي نسخة HTML من الرسالة.
');

// 4. الإرسال
try {
    $mailer->send($email);
    echo "تم إرسال البريد الإلكتروني بنجاح!\n";
} catch (\Exception $e) {
    echo "خطأ: " . $e->getMessage() . "\n";
}

قم بتشغيل السكريبت:

php send_email.php

إذا تم ضبط كل شيء بشكل صحيح، ستستلم الرسالة على العنوان المحدد.

4. أهم الطرق والكلاسات

4.1. Email::class - كلاس إنشاء الرسالة

التوقيع: new Email() (منشئ بدون معاملات)

الوظيفة: ينشئ كائن رسالة مع دوال ضبط (setters) لتعديل جميع السمات (المرسل، المستلم، الموضوع، نص الرسالة، المرفقات، إلخ).

مثال:

use Symfony\Component\Mime\Email;

$email = (new Email())
    ->from('sender@example.com')
    ->to('recipient@example.com')
    ->subject('موضوع الرسالة')
    ->text('نص عادي')
    ->html('
نص HTML
');