php email
v1.0.5
يوفر طريقة موجهة للكائنات لإرسال رسائل البريد الإلكتروني ووضعها في قائمة الانتظار.
هناك حاجة لإرسال رسائل بريد إلكتروني في جميع المشاريع تقريبًا، على سبيل المثال، لتسجيل المستخدم أو وظائف إعادة تعيين كلمة المرور. معظم رسائل البريد الإلكتروني المرسلة سهلة للغاية. الميزات المتطورة مثل تشفير PGP وما إلى ذلك ليست مطلوبة. توفر هذه المكتبة طريقة لإنشاء رسائل البريد الإلكتروني هذه دون إعداد PHPMailer (المكتبة الأساسية)، لإرسال رسائل بريد إلكتروني متعددة وحتى تأجيل إرسال إرسال البريد الإلكتروني باستخدام قائمة انتظار مدعومة بقاعدة بيانات - وكل ذلك في طريقة موجهة للكائنات.
الميزات هي:
EmailQueue .هذا المشروع مرخص بموجب GNU LGPL 3.0.
composer install technicalguru/email
يمكنك تنزيل حزم التعليمات البرمجية المصدر من صفحة إصدار GitHub
الفئة المركزية للتكوين هي EmailConfig . أنه يحمل جميع المعلومات اللازمة. لنبدأ بالهيكل العظمي الأساسي:
use TgEmailEmailConfig;
$config = new EmailConfig();
$config->setTimezone('Europe/Berlin');
$config->setDefaultSender('John Doe <[email protected]>');
$config->setSubjectPrefix('[MyAppName] ');
$config->setDebugAddress('[email protected]');
تقوم الأسطر أعلاه بإنشاء التكوين وتطلب منه استخدام المنطقة الزمنية Europe/Berlin عندما يحتاج إلى إنشاء طوابع زمنية. يعد هذا مطلوبًا بشكل أساسي عندما تكون رسائل البريد الإلكتروني في قائمة الانتظار ويلزم تسجيل الطابع الزمني. هذه القيمة اختيارية ويتم ضبطها افتراضيًا على UTC .
بعد ذلك، يتم تكوين عنوان المرسل الافتراضي. سيتم استخدام المرسل الافتراضي عندما لا يحدد البريد الإلكتروني المحدد الذي سيتم إرساله عنوان المرسل. سيتم شرح كيفية إنشاء عناوين البريد الإلكتروني بشكل أكبر أدناه.
يتم استخدام بادئة الموضوع في كل بريد إلكتروني يتم إرساله لاحقًا. سيتم بادئة المواضيع بهذه السلسلة. الافتراضي هو NULL ولن يقوم بتعديل الموضوع.
عنوان التصحيح مطلوب فقط عندما تحتاج إلى إرسال بريد اختباري.
ما زلنا بحاجة إلى معرفة مكان وجود خادم SMTP الخاص بنا. إذن هذه هي الطريقة التي تقوم بها بتعيين هذه القيم:
use TgEmailConfigSmtpConfig;
$host = 'smtp.example.com;
$port = 587;
$auth = TRUE;
$username = 'mySmtpUser';
$password = 'mySmtpPassword';
$secureOption = 'starttls';
$smtpConfig = new SmtpConfig($host, $port, $auth, $username, $password, $secureOption);
$config->setSmtpConfig($smtpConfig);
معظم الخيارات تشرح نفسها بنفسها. يُخبر $auth PHPMailer الأساسي ما إذا كان سيتم المصادقة باستخدام بيانات اعتماد المستخدم المحددة. يتم تعريف $secureOption بواسطة PHPMailer ويجب أن يكون له قيمة smtps أو starttls . راجع وثائق PHPMailer لمزيد من المعلومات.
يمكن تعيين كافة الخصائص باستخدام أداة ضبط:
use TgEmailConfigSmtpConfig;
$smtpConfig = new SmtpConfig();
$smtpConfig->setHost('smtp.example.com');
$smtpConfig->setPort(587);
// continue setup...
يمكن أيضًا تعيين بيانات اعتماد المصادقة باستخدام واجهة TgUtilsAuthCredentialsProvider من حزمة technicalguru/utils :
// Define here your provider
$provider = ...;
// Tell SMTP config
$smtpConfig->setCredentialsProvider($provider);
حان الوقت الآن لإنشاء كائن MailQueue المركزي الخاص بنا:
use TgEmailEmailQueue;
$mailer = new EmailQueue($config);
أنت جاهز لإرسال بريدك الإلكتروني الأول.
هناك طريقة سريعة وسهلة للتحقق مما إذا كان الإعداد يعمل بشكل صحيح:
$email = $mailer->createTestMail();
$rc = $mailer->send($email);
لقد قمنا بإعداد الحد الأدنى من المتطلبات لإرسال بريد إلكتروني:
use TgEmailEmail;
$email = new Email();
$email
->setSubject('Hello World')
->addTo('[email protected]', 'John Doe')
->addBcc('[email protected]')
->setReplyTo('[email protected]')
->setBody(Email::TEXT, 'The text e-mail body')
->setBody(Email::HTML, '<p>The HTML e-mail body</p>');
// Will return FALSE when sending fails
$rc = $mailer->send($email);
هذا كل شيء. مقتطف الكود أعلاه هو كل ما تحتاجه في كود التطبيق الخاص بك لإرسال رسائل البريد الإلكتروني. يجب أن يتم دفن التكوين والإعداد في مكان ما في إعداد البنية الأساسية لديك.
يعد إرفاق الملفات أو تضمين الصور أمرًا بسيطًا. ستحتاج إلى أن يكون الملف متاحًا وقابلاً للقراءة على نظام الملفات:
use TgEmailAttachment;
$myFile = new Attachment(Attachment::ATTACHED, 'file.pdf', NULL, '/local/path/to/file.pdf', 'application/pdf');
$myImage = new Attachment(Attachment::EMBEDDED, 'img.png', 'img1', '/local/path/to/img.png', 'image/png');
$email
->addAttachment($myFile)
->addAttachment($myImage);
لاحظ المعلمة الثالثة للصور المضمنة. فهو يحدد معرفًا فريدًا داخل بريد HTML الإلكتروني الخاص بك والذي يمكنك الرجوع إليه
// Using the embedded image
$myHTML = '<img src="cid:img1">';
سيترك MailQueue جميع مرفقاتك دون تغيير على نظام الملفات الخاص بك. ومع ذلك، في بعض الأحيان قد ترغب في التخلص من الملف بعد إرسال البريد الإلكتروني. يأخذ المنشئ وسيطتين إضافيتين:
$myFile = new Attachment(Attachment::ATTACHED, $filename, $cid, $path, $mimeType, TRUE, TRUE);
سيؤدي القيمة المنطقية الأولى إلى حذف الملف بعد إرسال البريد الإلكتروني بنجاح. يخبرنا المنطق المنطقي الثاني ما إذا كان من الممكن حذف الملف عند فشل الإرسال. باستخدام هذه المعلمات، لن تحتاج إلى الاهتمام بالملفات المؤقتة بعد الآن. خاصة عندما يتعلق الأمر بالانتظار والإرسال المؤجل.
يدعم MailQueue ما يسمى بأوضاع البريد. يخبرون كائن الإرسال بكيفية التعامل مع رسائل البريد الإلكتروني بشكل عام. يكون هذا أمرًا مريحًا عندما تقوم باختبار الإعداد، أو عندما تكون في بيئة تحتوي على عناوين بريد إلكتروني حقيقية (مثل بيئات اختبار قبول المستخدم) أو عندما لا يكون إرسال رسائل البريد الإلكتروني أمرًا منطقيًا.
هذه الأوضاع متوفرة:
EmailQueue::DEFAULT - هذه هي العملية العادية. يتم إرسال كافة رسائل البريد الإلكتروني على النحو المحدد.EmailQueue::BLOCK - سيمنع هذا إرسال أي بريد أو وضعه في قائمة الانتظار. رمز الإرجاع يكون دائمًا صحيحًا.EmailQueue::REROUTE - سيتم إرسال جميع رسائل البريد الإلكتروني إلى عنوان آخر، وعادة ما يكون عنوان المسؤول أو المطور ويتم تجاهل المستلمين المحددين للبريد الإلكتروني.EmailQueue::BCC - سيتم إرسال رسائل البريد الإلكتروني إلى المستلمين المقصودين ولكن يتم تعيين عناوين إضافية في BCC.يعد حظر جميع رسائل البريد الإلكتروني المراد إرسالها أو وضعها في قائمة الانتظار أمرًا سهلاً للغاية:
$mailer->setMailMode(EmailQueue::BLOCK);
يمكن استخدام نفس الطريقة على كائن EmailConfig المركزي.
أنت بحاجة إلى تكوين RerouteConfig ليتم تعيينه في التكوين الرئيسي. يمكنك ضبط هذا مقدمًا عند إنشاء كائن التكوين، أو كليًا عند ضبط وضع البريد:
use TgEmailConfigRerouteConfig;
// Create the config
$subjectPrefix = '[Rerouted]';
$recipients = array('[email protected]');
$rerouteConfig = new RerouteConfig($subjectPrefix, $recipients);
// And set the mail mode
$mailer->setMailMode(EmailQueue::REROUTE, $rerouteConfig);
أنت بحاجة إلى تعيين تكوين BccConfig في التكوين الرئيسي. يمكنك ضبط هذا مقدمًا عند إنشاء كائن التكوين، أو كليًا عند ضبط وضع البريد:
use TgEmailConfigBccConfig;
// Create the config
$recipients = array('[email protected]');
$bccConfig = new BccConfig($recipients);
// And set the mail mode
$mailer->setMailMode(EmailQueue::BCC, $bccConfig);
أحد عيوب إرسال رسائل البريد الإلكتروني مباشرة من رمز التطبيق هو أنه يستغرق وقتًا طويلاً. يحتاج المستخدم الخاص بك إلى الانتظار حتى يكتمل الإرسال قبل أن يتمكن من رؤية أي رد من طلبك. يعد وضع رسائل البريد الإلكتروني في قائمة الانتظار هو الحل حيث يتم تأجيل الإرسال (يفضل وظيفة cron) ويتلقى المستخدم استجابة طلبه بسرعة.
سوف تحتاج إلى كائن TgDatabaseDatabase لوضع رسائل البريد الإلكتروني في قائمة الانتظار. بخلاف ذلك، سوف يقوم EmailQueue بطرح استثناءات عند محاولة وضع رسائل البريد الإلكتروني في قائمة الانتظار. الرجاء الرجوع إلى وثائق TgDatabaseDatabase حول كيفية إنشاء كائن Database . قم بإعداد EmailsDAO و EmailQueue وفقًا لذلك على النحو التالي:
use TgEmailEmailsDAO;
$dao = new EmailsDAO($database);
$mailer = new EmailQueue($config, $dao);
سيقوم مرسل البريد تلقائيًا بإنشاء جدول الانتظار إذا لم يكن موجودًا.
بمجرد توفر EmailsDAO ، يمكنك بسهولة وضع رسائل البريد الإلكتروني في قائمة الانتظار:
// Create your email object here
$email = ...
// Queue it. Will return FALSE when sending fails
$rc = $mailer->queue($email);
يمكنك معالجة قائمة الانتظار في مكالمة أخرى أو أثناء وظيفة cronjob:
$mailer->processQueue($maxSeconds);
ستضمن الوسيطة $maxSeconds توقف المعالجة عند الوصول إلى الحد الزمني. الوسيطة اختيارية ويتم تعيينها بشكل افتراضي على 60 ثانية.
هناك طرق متعددة لإنشاء عناوين البريد الإلكتروني. تستخدم كافة مكونات البريد كائن EmailAddress . يمكنك استخدام هذا الكائن كوسيطة حيثما يتم توقع عناوين البريد الإلكتروني. توجد عدة طرق لإنشاء مثل هذا الكائن.
// From a string
$address = EmailAddress::from('[email protected]');
$address = EmailAddress::from('<[email protected]>');
$address = EmailAddress::from('John Doe <[email protected]>');
// From email string and name
$address = EmailAddress::from('[email protected]', 'John Doe');
// From another object
$obj = new stdClass;
$obj->name = 'John Doe';
$obj->email = '[email protected]';
$address = EmailAddress::from($obj);
// From another EmailAddress
$address = EmailAddress::from($anotherEmailAddressObject);
وهذا يعني أنه يمكنك استخدام هذه النكهات عند إنشاء رسائل البريد الإلكتروني:
$email->addTo('John Doe <[email protected]>');
$email->addTo('[email protected]', 'John Doe');
$email->addTo(array('John Doe <[email protected]>', $anotherEmailAddressObject, $obj);
يمكن أيضًا إنشاء كائنات التكوين المقدمة أعلاه باستخدام سلاسل JSON أو الكائنات أو المصفوفات الترابطية. تصف المقتطفات التالية كائنات JSON بتدوين قصير.
SmtpConfig:
-----------
{
"host": "www.example.com",
"port": 587,
"debugLevel": 0,
"auth": true,
"secureOption": "starttls",
"charset": "utf8",
"credentials": {
"user": "username",
"pass": "password"
}
},
RerouteConfig:
--------------
{
"recipients": "[email protected]",
"subjectPrefix": "[Rerouted]"
},
BccConfig:
----------
{
"recipients": "[email protected]"
},
EmailConfig:
------------
{
"timezone": "Europe/Berlin",
"mailMode": "default",
"smtpConfig": {... see above ...},
"rerouteConfig": {... see above ...},
"bccConfig": {... see above ...},
"debugAddress": "[email protected]",
"defaultSender": "[email protected]",
"subjectPrefix": "[PHPUnitTest] "
}
توفر كل فئة من فئات التكوين طريقة from() ثابتة تأخذ هذه الأنواع كوسيطة وتعيد كائن التكوين نفسه:
$smtpConfig = SmtpConfig::from($jsonStringOrObjectOrAssocArray);
$rerouteConfig = RerouteConfig::from($jsonStringOrObjectOrAssocArray);
$bccConfig = BccConfig::from($jsonStringOrObjectOrAssocArray);
$emailConfig = EmailConfig::from($jsonStringOrObjectOrAssocArray);
من الممكن تمرير مجموعة من كائنات Email لوظائف send() وقائمة queue() . ومع ذلك، خاصة بالنسبة لإرسال رسائل البريد الإلكتروني على الفور، يجب أن تدرك أن هذا قد يستغرق بعض الوقت. الإستراتيجية الأفضل هي وضع الرسائل الجماعية في قائمة الانتظار.
لن يتم تنفيذ معظم اختبارات PHPUnit في حالة عدم توفر خادم SMTP أو قاعدة بيانات. ستقوم اختبارات الوحدة بالتحقق من متغير البيئة EMAIL_TEST_SMTP و EMAIL_DATABASE . يوجد برنامج نصي bash متاح، set-test-env.sh يقوم بإنشاء تلك المتغيرات لك. انسخه إلى set-local-test-env.sh على سبيل المثال واتبع التعليمات الموجودة في الملف.
أبلغ عن خطأ، أو اطلب تحسينًا أو طلب سحب على GitHub Issue Tracker.
