ایمیل

این بخش توضیح می‌دهد چگونه می‌توانید از افزونه خود ایمیل ارسال کنید، با استفاده از کلاس Mail جوملا یا کلاس MailTemplate.

برای اینکه این امکان به درستی کار کند باید مطمئن شوید که نمونه جوملای شما به درستی در بخش تنظیمات سراسری (Global Configuration) / تب سرور (Server) پیکربندی شده است و گزینه «ارسال ایمیل تست» (Send Test Mail) به درستی عمل می‌کند.

همچنین یک کامپوننت نمونه به نام com_sendmail وجود دارد که می‌توانید آن را دانلود و اجرا کنید تا با Mail جوملا آزمایش نمایید. دستورالعمل استفاده در انتهای همین صفحه موجود است.

ارسال ایمیل

گرفتن نمونه Mail جوملا

اولین مرحله گرفتن نمونه Mail جوملا است. ساده‌ترین روش به شکل زیر است:

use Joomla\CMS\Factory;
use Joomla\CMS\Mail\MailerFactoryInterface;
$mailer = Factory::getContainer()->get(MailerFactoryInterface::class)->createMailer();

زمانی که جوملا راه‌اندازی می‌شود، یک ورودی در Dependency Injection Container (DIC) قرار می‌گیرد به این صورت:

- کلید: نام کامل کلاس `MailerFactoryInterface` به صورت رشته

- مقدار: کدی که یک نمونه `MailerFactory` برمی‌گرداند

در اینجا ما این نمونه را از کانتینر گرفته و متد `createMailer()` را صدا زده‌ایم تا نمونه Mail جوملا را بگیریم.

اگر کد شما در کلاس کنترلر یا مدل یک کامپوننت نوشته شده و از MVCFactory برای ساخت آن استفاده شده، می‌توانید MVCFactory را وادار کنید تا نمونه `MailerFactory` را به شما بدهد.

برای اینکار کلاس کنترلر یا مدل شما باید:

- یک getter و setter برای `MailerFactory` داشته باشد (که می‌توانید با استفاده از `MailerFactoryAwareTrait` این‌ها را بسازید)

- اعلام کند که این getter و setter را دارد، با پیاده‌سازی اینترفیس `MailerFactoryAwareInterface`

نمونه کد:

use Joomla\CMS\Factory;
use Joomla\CMS\Mail\MailerFactoryAwareTrait;
use Joomla\CMS\Mail\MailerFactoryAwareInterface;
class MyController extends ... implements MailerFactoryAwareInterface
{
use MailerFactoryAwareTrait;
public function sendMail()  
{  
    $mailer = $this->getMailerFactory()->createMailer();  
    ...  
}  
}

MVCFactory زمانی که کنترلر شما را می‌سازد، چک می‌کند که آیا کلاس شما اینترفیس `MailerFactoryAwareInterface` را پیاده‌سازی کرده یا خیر، اگر کرده باشد، setter مربوطه را صدا زده و `MailerFactory` را تنظیم می‌کند. سپس شما با getter می‌توانید این نمونه را بگیرید و `createMailer()` را فراخوانی کنید.

فرستادن

وقتی نمونه Mail ($mailer) را دارید، می‌توانید با API آن جنبه‌های مختلف ایمیل را تنظیم کنید.

این نمونه Mail به طور پیش‌فرض داده‌های تعریف شده در Global Configuration / Server را می‌گیرد. مثلاً اگر فرستنده را تنظیم نکنید، اطلاعات فرستنده از پیکربندی سراسری گرفته می‌شود.

حداقل باید موارد زیر را تنظیم کنید:

- آدرس ایمیل گیرنده

- موضوع پیام

- متن بدنه پیام

مثال:

$mailer->addRecipient(این آدرس ایمیل توسط spambots حفاظت می شود. برای دیدن شما نیاز به جاوا اسکریپت دارید');
$mailer->setSubject('test');
$mailer->setBody('Hello!');
try
{
$mailer->send();
$this->app->enqueueMessage("Mail successfully sent", 'info');
}
catch (\Exception $e)
{
$this->app->enqueueMessage("Failed to send mail, " . $e->getMessage(), 'error');
}

 اگر ارسال ایمیل شکست بخورد، متد send() یک Exception پرتاب می‌کند، بنابراین بهتر است در یک بلوک try/catch فراخوانی شود.

کدی که بالا دیدید در برنامه نمونه com_sendmail استفاده شده که در انتهای این بخش توضیح داده شده است.

عیب‌یابی

اگر در ارسال ایمیل به مشکل خوردید، پیام‌های نمایش داده شده ممکن است کمک چندانی نکنند.

در این‌صورت، باید در بخش Global Configuration / Logging گزینه «Log Almost Everything» را فعال کنید. این کار باعث می‌شود تمام تعاملات سطح پایین با سرور ایمیل در فایل لاگ ذخیره شود.

(ممکن است تعداد زیادی خط با پیغام خطا ببینید، اما آن‌ها لزوماً خطا نیستند!)

گاهی دلیل مشکل واضح نیست. مثلاً بعد از تنظیم $mailer->isHtml() برای ارسال ایمیل با فرمت HTML ممکن است از سرور چیزی شبیه این دریافت کنید:

550-We're sorry, but we can't send your email. Either the subject matter, a link, or an attachment potentially contains
550 spam, or phishing or malware. Please check or edit your message and try sending it again.

در اینجا SMTP سرور اجازه ارسال ایمیل از نوع(Content-Type) متن/صفحه وب (text/html) را نمی‌دهد.

قالب‌های ایمیل (Mail Templates)

شما همچنین می‌توانید از قالب‌های ایمیل برای ارسال ایمیل استفاده کنید.

قالب‌های ایمیل جوملا را می‌توانید با رفتن به پیشخوان مدیریت (Administrator System Dashboard) و انتخاب Mail Templates در پنل قالب‌ها (Templates) مشاهده و ویرایش کنید.

اگر با این موضوع ناآشنا هستید، بهتر است ابتدا در یک نمونه جوملای آزمایشی با آن‌ها کار کنید تا بهتر متوجه نکات زیر شوید.

همچنین به تاثیر تغییر گزینه‌های پیکربندی قالب‌های ایمیل توجه کنید.

تعریف قالب‌های ایمیل

جوملا به صورت پیش‌فرض امکاناتی برای ایجاد قالب‌های ایمیل ندارد.

به جای آن، باید قالب‌ها را در کد خود ایجاد کنید، مثلاً در فایل اسکریپت نصب (installation script) خود با استفاده از APIهای قالب‌های ایمیل (Mail Template APIs).

این APIها توابع استاتیک زیر را فراهم می‌کنند:

- `createTemplate`

- `updateTemplate`

- `deleteTemplate`

و داده‌ها به جدول دیتابیس `#__mail_templates` نگاشته می‌شوند.

برای هر قالب که تعریف می‌کنید باید موارد زیر را مشخص کنید:

- کلید قالب (template key) — که باید شامل نام افزونه شما باشد، مثلاً `'com_sendmail.example'`

- متن موضوع ایمیل — که به صورت یک کانستنت زبان (Language Constant) تعریف خواهد شد

- متن بدنه ایمیل — که آن هم به صورت یک کانستنت زبان تعریف می‌شود

- آرایه‌ای از تگ‌ها (tags) — فیلدهایی که در موضوع و بدنه ایمیل جایگزین توسط مقادیر می‌شوند

لازم است که کانستنت‌های زبان موضوع و متن ایمیل را در فایل زبان `.ini` خود (چه سایت و چه مدیریت بسته به جایی که ایمیل را ارسال می‌کنید) تعریف کنید.

متن بدنه ایمیل را می‌توانید به صورت HTML یا متن ساده تعریف کنید.

همچنین باید چند کانستنت زبان دیگر را که جوملا بر اساس کلید قالب شما می‌سازد، تعریف نمایید.

برای کلید «com_sendmail.example» در فایل های زبان مدیریت با پسوند `.sys.ini` باید موارد زیر را تعریف کنید:

- `COM_SENDMAIL_MAIL_EXAMPLE_TITLE`

- `COM_SENDMAIL_MAIL_EXAMPLE_DESC`

- `COM_SENDMAIL`

این موارد در فرم «قالب‌های ایمیل» (Mail Templates) پنل مدیریت نمایش داده می‌شوند.

و در فایل‌های زبان `.ini` بخش مدیریت، باید (دوباره) برای هرکدام:

- `COM_SENDMAIL_MAIL_EXAMPLE_TITLE`

- `COM_SENDMAIL_MAIL_EXAMPLE_DESC`

تعریف شود، چون هنگام مشاهده یا ویرایش یک قالب ایمیل نمایش داده می‌شوند.

پیکربندی قالب‌های ایمیل

وقتی قالب ایمیل خود را ایجاد کردید، یک مدیر سایت می‌تواند آن را از طریق بخش قالب‌های ایمیل در پنل مدیریت ویرایش کند.

مدیر می‌تواند متن موضوع و بدنه ایمیل را تغییر دهد، محل قرارگیری تگ‌های تعریف شده توسط شما را مشخص کند، و ضمیمه‌هایی را اضافه نماید (ضمائم می‌توانند از پوشه‌ای خارج از پوشه‌های تحت کنترل جوملا باشند، اگر این گزینه فعال باشد).

بدنه HTML ایمیل (اگر تنظیم شده باشد) فقط زمانی نشان داده می‌شود که گزینه پیکربندی قالب‌های ایمیل «فرمت ایمیل» (Mail Format) شامل HTML باشد.

اگر گزینه پیکربندی قالب‌های ایمیل «تنظیمات ایمیل برای هر قالب» (Per Template Mail Settings) فعال باشد، مدیر می‌تواند گزینه‌های بیشتری را از طریق تب Options در هنگام ویرایش قالب ایمیل تنظیم کند.

اگرچه وقتی قالب ایمیل را می‌سازید موضوع و بدنه را به صورت کانستنت زبان تعریف می‌کنید، هنگام نمایش قالب، این کانستنت‌ها ترجمه شده و به زبان مشخصی نمایش داده می‌شوند.

اگر مدیر قالبی را تغییر داده و ذخیره کند، قالب در جدول `#__mail_templates` ذخیره می‌شود و ستون زبان (`language`) بر اساس زبان نمایش داده شده آن مقداردهی می‌شود.

این بدین معنی است که در جدول `#__mail_templates` می‌توانید چند رکورد برای هر قالب ایمیل داشته باشید:

- یک رکورد اصلی که قالب را همانطور که تعریف کردید دارد و فیلد زبان خالی است

- یک رکورد برای هر زبان که مدیر قالب را برای آن زبان تغییر داده است

هنگامی که شما در کد افزونه خود قالبی را برای ارسال ایمیل استفاده می‌کنید باید زبان را مشخص کنید. جوملا اول به دنبال رکوردی با زبان مشخص شده می‌گردد (که احتمالا مدیر آن را ویرایش کرده)، و اگر پیدا نکرد، رکورد پیش‌فرض و اصلی که توسط کامپوننت ساخته شده را استفاده می‌کند.

ترجمه متن درباره توسعه جوملا و استفاده از قالب ایمیل (Mail Template) به فارسی:

ارسال ایمیل با استفاده از قالب ایمیل (Mail Template)

کلاس MailTemplate مانند یک پوشش دور کلاس Mail عمل می‌کند، بنابراین شما می‌توانید گیرنده‌ها، فایل‌های پیوست، آدرس پاسخ‌دهی (reply-to) را اضافه کرده و ایمیل را از طریق APIهای قالب ایمیل ارسال کنید.

ابتدا باید نمونه Mail را همانطور که در بالا توضیح داده شده دریافت کنید، اما پس از آن از نمونه MailTemplate استفاده نمایید:

$mailer = Factory::getContainer()->get(MailerFactoryInterface::class)->createMailer();

// اگر می‌خواهید از زبان کاربر فعلی استفاده کنید...
$user = $this->app->getIdentity();
// قالب ایمیل را با شناسه قالب، زبان و نمونه mailer مقداردهی کنید
$mailTemplate = new MailTemplate(
'com_sendmail.example',
$user->getParam('language', $this->app->get('language')),
$mailer
);
// گیرنده را از طریق MailTemplate اضافه کنید
$mailTemplate->addRecipient(این آدرس ایمیل توسط spambots حفاظت می شود. برای دیدن شما نیاز به جاوا اسکریپت دارید');
// اینجا قالب ایمیل با داده‌هایی که ارائه می‌دهید جایگزین تگ‌ها می‌شود
// در مثال com_sendmail تگ‌ها 'name'، 'p1' و 'p2' هستند، بنابراین آرایه داده‌ای با این کلیدها لازم است
$mailTemplate->addTemplateData([
'name' => $data['name'],
'p1' => $data['p1'],
'p2' => $data['p2']
]);
// ارسال ایمیل با استفاده از MailTemplate؛ در صورت شکست، استثنا پرتاب می‌شود
try {
$mailTemplate->send();
} catch (\Exception $e) {
$this->app->enqueueMessage("ارسال ایمیل ناموفق بود، " . $e->getMessage(), 'error');
}

 مثال کامپوننت com_sendmail

شما می‌توانید این کامپوننت نمونه com_sendmail را دانلود و نصب کنید که ارسال ایمیل را هم با استفاده از کلاس Mail و هم کلاس MailTemplate نشان می‌دهد.

در فرآیند نصب، com_sendmail یک قالب ایمیل با کلید `'com_sendmail.example'` ایجاد می‌کند که می‌توانید از طریق مدیریت قالب‌های ایمیل در پنل ادمین آن را مشاهده و ویرایش کنید.

برای اجرای کامپوننت، به آدرس زیر بروید: 

<your domain>/index.php?option=com_sendmail

این کامپوننت یک فرم نمایش می‌دهد که:

- به شما امکان انتخاب می‌دهد که ایمیل با Mail ارسال شود یا MailTemplate 

- داده‌های مورد نیاز بر اساس انتخاب شما را دریافت می‌کند

همچنین می‌توانید با فعال کردن لاگ‌ها از طریق تنظیمات سراسری / Logging، تعاملات پایین‌رده ارسال ایمیل را در فایل لاگ مشاهده کنید.