JMail — Отправка почтовых сообщений

Объект для работы с почтой

Ссылка на глобальный объект электронной почты JMail получается с помощью класса JFactory. Это создание нашего объекта JMail.

$mailer = & JFactory::getMailer();

В результате мы получим объект класса JMail, который объявлен по адресу /libraries/joomla/mail/mail.php и является потомком класса PHPMailer. Все необходимые файлы подключаются сами по необходимости.

Библиотека PHPMailer — Это внешняя библиотека для отправки почты расположенная по адресу /libraries/phpmailer. Служит для передачи электронной почты, позволяющий, в частности, вкладывать в сообщение несколько файлов, посылать копии CC и BCC, устанавливать атрибут REPLY-TO, использовать в сообщениях HTML, работать с резервными SMTP-серверами, переносить строки по словам. Он может посылать сообщения с через sendmail, PHP mail() или непосредственно по протоколу SMTP.

Установка отправителя

Отправитель письма устанавливается с помощью метода setSender. Функция принимает массив с адресом электронной почты и именем в качестве аргумента. Мы получили имя и адрес электронной почты из глобальной конфигурации сайта. Они устанавливаются в административной части сайта (Общие настройки / Настройки почты). От этого имени будет отправлена почта.

$config =& JFactory::getConfig();
$sender = array($config->get('config.mailfrom'), $config->get('config.fromname') );
$mailer->setSender($sender);

Установка получателя

Вы устанавливаете получатель электронной почты с помощью метода addRecipient. Для того что-бы задать e-mail адрес текущего авторизованного пользователя, мы возьмём его из объекта пользователя.

$user =& JFactory::getUser();
$recipient = $user-> email;
$mailer->addRecipient($recipient);

Если у нас есть несколько адресатов, мы можем отправить их в виде массива.

$recipient = array('person1@domain.com', 'person2@domain.com', 'person3@domain.com');

Создание письма

Мы должны указать тему письма и создать содержимое. Тема письма устанавливается с помощью метода JMail->setSubject.

Простой способ создания сообщения в виде строки текста. Используйте функцию JMail->setBody для добавления сообщения к письму. Вы можете так же прикрепить файл JMail->addAttachment. В качестве аргумента может быть имя одного файла или массив имён нескольких.

$body   = "Your body string\nin double quotes if you want to parse the \nnewlines etc";
$mailer->setSubject('Your subject string');
$mailer->setBody($body);
// Optional file attached
$mailer->addAttachment(PATH_COMPONENT.DS.'assets'.DS.'document.pdf');

HTML-формат письма

Если вы предпочитаете HTML-формат письма, вы должны это указать. Это делается с помощью метода JMail->IsHTML. Темы и любые вложения обрабатываются, как указано выше, за исключением изображений встроенных в HTML. Они обрабатываются методом JMail->AddEmbeddedImage.

$body   = '<h2>Our mail</h2>'
         .'<div>A message to our dear readers'
         .'<img src="cid:logo_id" alt="logo"/></div>';
$mailer->isHTML(true);
$mailer->setBody($body);
// Optionally add embedded image
$mailer->AddEmbeddedImage(PATH_COMPONENT.DS.'assets'.DS.'logo128.jpg', 'logo_id', 'logo.jpg', 'base64', 'image/jpeg');

Как правило, вы отправляете все изображения на сервер и вставляете обычным HTML-тегом изображения, для уменьшения размера почты и времени отправки.

Дополнительные опции для писем

Это редкоиспользуемые методы, но в редких случаях бывают необходимы и добавляют гибкости при отправке почты. Всем перечисленным методам ниже можно указывать несколько значений в виде массива или строкой.

JMail->addReplyTo — добавить адрес почты для ответа. Пример одного адреса — array(’person1@domain.com’, ’username’). Несколько адресов соответственно — это вложенный массив.
JMail->addBCC — Добавить получателей слепой точной копии (BCC).
JMail->addCC — Добавить получателей точной копии (CC).
JMail->addAttachment — Добавить файл(ы) к письму. Указывать нужно абсолютный путь до файла на вашем сервере.

Т.к JMail является потомком PHPMailer, то доступны все методы и из него, прочитать о нем подробно можно по ссылкам ниже.

Отправка почты

Письмо отправляется с помощью метода Send. Он возвращает true при успешной отправке или объект ошибки JError. Все письма будут отправляться в кодировке UTF-8. Это необходимо иметь ввиду, иначе письмо будет затруднительно прочитать.

$send =& $mailer->Send();
if ($send !== true) {
    echo 'Error sending email: '.$send->message;
} else {
    echo 'Mail sent';
}

Во всяком случае лучше всего написать собственный обработчик ошибок с помощью класса JError.

Альтернативный способ отправки писем

Существует класс JUtility, который без явного создания объекта поможет отправить письмо. Это просто немного упрощенная версия того что описано выше. Делает это примерно так.

jimport('joomla.utilities.utility');
 
$fromEmail = 'admin@mysite.ru'; // отправитель, почта
$fromName = 'Test Server'; // отправитель, имя
 
$email = 'admin@example.com'; // кому
 
$subject = 'Test Mail Message'; // тема письма
 
$convertedBody = '<p>TEST MESSAGE</p>'; // сообщение в html
 
$filename = JPATH_BASE.DS.'images'.DS.'stories'.DS.'articles.jpg'; // прикрепляемый файл
 
// отправляем
 
JUtility::sendMail($fromEmail, $fromName, $email, $subject, $convertedBody, true, null, null, $filename );

Почему не нужно использовать функцию mail()?

Отправляя письма через mail(), вы сами должны следить за всеми заголовками, конвертировать необходимые вещи через base64, учитывать кодировку и многое другое. Более того, JMail может отправлять письма различными способами: SMTP, sendmail и функция mail(). Настроить это можно в Общих настройках / Сервер.

Так что лучше использовать готовый набор библиотек, где все уже учтено и отлажено и готово к работе.

Примеры в компонентах Joomla

Объект JMail используется для отправки почты в компоненте контактов (joomla/components/com_contact/controller.php).

$recipient = array('person1@domain.com', 'person2@domain.com', 'person3@domain.com');