Уведомления

Модуль отправляет уведомления на электронный ящик (e-mail) или SMS-уведомления.

Начиная с версии 6.0.8.9 модуль полностью заменил подключения «Почта» и «SMS».

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

Подключение

Подключаемая часть – файл modules/postman/postman.inc.php. В нем описан класс Postman_inc. В модуле к объекту класса можно обратиться через переменную $this->diafan->_postman. Экземпляр класса создается при первом вызове переменной.

Среди функций подключения две широко применимы и могут быть использованы в других частях CMS: message_add_mail() и message_add_sms(). Остальные определены для внутреннего использования модулем «Уведомления».

Обе функции ставят уведомление в очередь на отправку. Если отключена настройка «Автоматическая отправка уведомлений», то письмо отправлено не будет. Этот режим можно отключать для тестирования работы скриптов, чтобы просто увидеть какие формируются сообщения, но пользователям ничего не отправлять.

На работу функции message_add_mail() влияет еще настройка «Включить отложенную отправку для почты». Если она выключена, письмо просто будет отправлено.

Режим «Включить отложенную отправку для почты» позволяет только инициировать отправку. Скрипт не будет ждать ответа, поэтому отправка письма никак не повлияет на время ответа сервера. Иногда сервер тратить заметное время на подключение к почтовой службе и пользователю приходится ждать ответа на свои действия из-за того, что обработка его действий включает отправку письма. Режим отложенной загрузки решает эту проблему.

Аналогично для функции message_add_sms() и настройки «Включить отложенную отправку для SMS».

Код вызова этих двух функций полностью заменяет устаревший (начиная со сборки 6.0.8.9) код, использующий подключение «Почта».

Пример:

Устаревший код:

Custom::inc(ABSOLUTE_PATH.'includes/mail.php');
send_mail("to@anymail.com", "Заголовок письма", "Содержимое письма<br>Можно использовать HTML", "from@site.ru");

И подключение «SMS».

Пример:

Устаревший код:

Custom::inc(ABSOLUTE_PATH.'includes/sms.php');
Sms::send('Сообщение пользователю', '797777777777');

Методы подключения разделены на три части.

Работа с базой данных

Эта группа описана в файле modules/postman/inc/postman.inc.db.php. К методам для работы с базой данных нужно добавлять префикс db_. Например, $this->diafan->_postman->db_add().

Методы

add (mixed(string|array) $recipient, string $subject, string $body, [string $from = ''], [string $type = 'mail'], [boolean $auto = true]) – Добавляет уведомление.

  • mixed(string|array) $recipient: получатель/получатели
  • string $subject: тема письма
  • string $body: содержание письма
  • string $from: адрес отправителя
  • string $type: тип уведомления: mail – письмо, sms – короткое сообщение
  • boolean $auto: метод отправки уведомления: false – ручной, true – автоматический

Пример:

Добавим в базу данных модуля письмо на отправку.

$this->diafan->_postman->db_add("to@anymail.com", "Заголовок письма", "Содержимое письма<br>Можно использовать HTML", "from@site.ru", "mail", true);

integer count_sent () – Возвращает количество уведомлений, требующих отправки.

Пример:

echo 'Количество писем и SMS, ожидающих отправку: '.$this->diafan->_postman->db_count_sent();

Выведет: Количество писем и SMS, ожидающих отправку: 7

Работа с отложенной нагрузкой

Эта группа описана в файле modules/postman/inc/postman.inc.defer.php. К методам для работы с отложенной нагрузкой нужно добавлять префикс defer_. Например, $this->diafan->_postman->defer_init().

Методы

void init () – Инициирует отложенную отправку уведомлений.

Пример:

Если включены настройки «Автоматическая отправка уведомлений» и «Включить отложенную отправку для почты», инициируем отложенную отправку.

if($this->diafan->configmodules('auto_send', 'postman') && $this->diafan->configmodules('mail_defer', 'postman'))
{
    
$this->diafan->_postman->defer_init();
}

Работа с сообщениями

Эта группа описана в файле modules/postman/inc/postman.inc.message.php. К методам для работы с сообщениями нужно добавлять префикс message_. Например, $this->diafan->_postman->message_add_mail().

Методы

string add_mail (string|array $recipient, string $subject, string $body, [string $from = '']) – Добавляет письмо в список почтовых отправлений.

  • string|array $recipient: получатель/получатели
  • string $subject: тема письма
  • string $body: содержание письма
  • string $from: адрес отправителя

Пример:

Отправляем сообщение на почту пользователя.

$this->diafan->_postman->message_add_mail("to@anymail.com", "Заголовок письма", "Содержимое письма<br>Можно использовать HTML", "from@site.ru");

Поле «Отправитель» рекомендуем оставлять пустым, чтобы использовался e-mail из настроек модуля «Уведомления». Если адрес почты не будет совпадать с тем, для которого настроена SMTP-авторизация, то письма могут не проходить спам-фильтры почтовых служб.

Поэтому лучше отправлять так:

$this->diafan->_postman->message_add_mail("to@anymail.com", "Заголовок письма", "Содержимое письма.<br>Можно использовать HTML.");

mixed string add_sms (string $text, string $to) – Добавляет SMS в список почтовых отправлений.

  • string $text: текст SMS
  • string $to: номер получателя

Пример:

$this->diafan->_postman->message_add_sms('Сообщение пользователю', '797777777777');

boolean send (mixed(array|string) $id) – Отправляет уведомление.

  • mixed(array|string) $id: идентификатор уведомления

Пример:

$id = DB::query_result("SELECT id FROM {postman} LIMIT 1");
if(
$this->diafan->_postman->send($id))
{
    echo
'Уведомление отправлено.';
}
else
{
    echo
'Уведомление не отправлено.';
}

Уведомления

В административной части модуля можно отправить письмо или SMS и увидеть очередь уведомлений. Если в настройках модуля отмечена опция «Удалять отправленные уведомления», то в списке будут только письма и SMS в очереди на отправку или те, что не удалось отправить. Здесь можно увидеть ошибку, которая появилась при попытке отправить уведомление. Если же настройка не отмечена, то в списке будут и все отправленные уведомления.

Список уведомлений

Поля формы добавления / редактирования уведомления

Редактирование уведомления

Настройки

Настройки

Настройки

Настройки

SMS-операторы

К модулю можно подключить бэкенды для работы с различными SMS-операторами. Добавлено в версии 6.0.9.10.

Для этого нужно разработать несколько файлов стандартной структуры и разместить папку с этими файлами в папку postman/backend. После этого в настройках модуля появиться новый поставщик услуг во вкладке «SMS».

Бэкенд должен иметь уникальное название латинскими буквами (по примеру bytehand, smsc и др.). Для примера будем использовать название myservice.

В папке postman/backend/myservice могут находиться следующий файлы:

  • postman.myservice.admin.php
  • postman.myservice.admin.js
  • postman.myservice.sms.php

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

Рассмотрим структуру стандартных файлов

postman.myservice.admin.php

Файл содержит настройки бэкенда, подгружаемые выборе поставщика услуг.

Структура файла:

Пример:

// ошибка 404 при прямом вызове файлов
if (! defined('DIAFAN'))
{
    
$path = __FILE__;
    while(!
file_exists($path.'/includes/404.php'))
    {
        
$parent = dirname($path);
        if(
$parent == $path) exit;
        
$path = $parent;
    }
    include
$path.'/includes/404.php';
}

// наследуем класс Diafan, чтобы был доступен объект $this->diafan
class Postman_myservice_admin extends Diafan
{
    public
$config = array(
        
"name" => 'Название бэкенда, выводимое администратору',
        
// настройки расширения
        // ключи этого массива - название настроек латинскими буквами
        
"params" => array(
            
// можно указать просто текстовое описание настройки
            // тогда она будет редактироваться как строка
            
'param1' => 'Название первой настройки',

            
// можно указать массив данных, тогда есть возможность
            // задать тип данных и подсказку
            
'param2' => array(
                
// название второй настройки
                
'name' => 'Ключ к API',

                
// доступны следующие типы:
                // text - строка, по умолчанию
                // checkbox - галочка
                // select - список
                // info - название выводиться текстом без редактирования
                // none - не отображается, но сохраняется
                
'type' => 'text',

                
// значение списка, если указан тип select
                
'select' => array(
                    
'ключ1' => 'значение1',
                    
'ключ2' => 'значение2',
                    
'ключ3' => 'значение3',
                ),

                
// подсказка
                
'help' => 'Ключ запросите у SMS-оператора.',
            ),

            
// можно определить свою функцию для вывода поля и его сохранения
            
'param3' => 'Название третьей настройки',
        )
    );

    
/**
     * Своя функция на редактирования настройки param3
     *
     * @param string $value значение для param3
     * @param array $values значение всех полей настроек, ключ - название поля
     * @return void
     */
    
public function edit_variable_param3($value, $values)
    {
        echo
'<div class="unit">
            <div class="infofield">Название поля</div>
            Значение поля
        </div>'
;
    }

    
/**
     * Своя функция на сохранение настройки param3
     * функция возвращает значение, которое нужно сохранить (не обязательно)
     *
     * @return mixed значение
     */
    
public function save_variable_param3()
    {
        
// сохраняет данные
        
return $value;
    }
}

postman.myservice.admin.js

При наличии этот JS-файл автоматически подключается в интерфейс настроек.

postman.myservice.admin.sms.php

Отправление SMS.

Пример:

// ошибка 404 при прямом вызове файлов
if (! defined('DIAFAN'))
{
    
$path = __FILE__;
    while(!
file_exists($path.'/includes/404.php'))
    {
        
$parent = dirname($path);
        if(
$parent == $path) exit;
        
$path = $parent;
    }
    include
$path.'/includes/404.php';
}

// наследуем класс Diafan, чтобы был доступен объект $this->diafan
class Postman_myservice_admin_sms extends Diafan
{
    
/**
     * Отправляет SMS
     *
     * @param string $text текст SMS
     * @param string $to номер получателя
     * @param string $error_output вывод ошибки
     * @param string $trace_output вывод трассировки
     * @return boolean
     */
    
public function send($text, $to, &$error_output, &$trace_output)
    {
        
// функция отправляет SMS
        // настройки бэкенда доступны через настройки модуля:
        // $this->diafan->configmodules("названиеБэкенда_названиеНастройки", 'postman');
    
}
}

Готовые интеграции

В стандартную сборку DIAFAN.CMS включены бэкенды «Byte Hand» и «SMSC». Другие бэкенды можно установить из дополнений.

База данных

{postman} – Уведомления

Файлы

  1. modules/postman/admin/js/postman.admin.config.js – настройки модуля, JS-сценарий;

  2. modules/postman/admin/postman.admin.php – редактирование почтовых отправлений;

  3. modules/postman/admin/postman.admin.action.php – обработка POST-запросов в административной части модуля;

  4. modules/postman/admin/postman.admin.config.php – настройки модуля;

  5. modules/postman/admin/postman.admin.count.php – количество неотправленных уведомлений для меню административной панели;

  6. modules/postman/backend/bytehand/postman.bytehand.admin.php – настройки SMS-провайдера «Byte Hand»;

  7. modules/postman/backend/bytehand/postman.bytehand.sms.php – работа с SMS-оператором «Byte Hand»;

  8. modules/postman/backend/smsc/postman.smsc.admin.php – настройки SMS-провайдера «SMSC»;

  9. modules/postman/backend/smsc/postman.smsc.sms.php – работа с SMS-оператором «SMSC»;

  10. modules/postman/inc/postman.inc.db.php – подключение модуля «Уведомления» для работы с базой данных;

  11. modules/postman/inc/postman.inc.message.php – подключение модуля «Уведомления» для работы с сообщениями;

  12. modules/postman/postman.exec.php – обрабатывает полученные данные из формы;

  13. modules/postman/postman.inc.php – подключение модуля «Уведомления»;

  14. modules/postman/postman.install.php – установка модуля;

  15. modules/postman/postman.send.php – HTTP код 200 (OK) для отправки уведомлений.

Дополнения

Ваши комментарии и дополнения

Ваш комментарий будет первым.

Зарегистрируйтесь или авторизируйтесь для того, чтобы оставить комментарий.