Перейти к содержимому
M
Все статьи
Технологии 8 мин чтения

Уведомления из плагина Moodle: Messaging API, провайдеры сообщений и каналы доставки

Как отправлять уведомления из плагина Moodle: db/messages.php, объект \core\message\message, message_send, каналы доставки и настройки пользователей.

Как отправлять уведомления из плагина Moodle: db/messages.php, объект \core\message\message, message_send, каналы доставки и настройки пользователей.

Уведомление из плагина — это не просто mail() и не прямая отправка по SMTP. Если вы отправляете письма обходным путём, пользователь не сможет их отключить, администратор не увидит их в настройках, а на сайтах с несколькими каналами доставки (почта, всплывающие окна, мобильное приложение) ваши сообщения до людей не дойдут. Правильный способ — Messaging API: плагин объявляет тип сообщения и отправляет его через message_send(), а доставку берёт на себя система.

Провайдер сообщений

Сначала плагин сообщает Moodle, какие виды уведомлений он умеет отправлять. Для этого создаётся файл db/messages.php:

defined('MOODLE_INTERNAL') || die();

$messageproviders = [
    'debt_reminder' => [],
    'document_checked' => [
        'defaults' => [
            'popup' => MESSAGE_PERMITTED + MESSAGE_DEFAULT_LOGGEDIN + MESSAGE_DEFAULT_LOGGEDOFF,
            'email' => MESSAGE_PERMITTED + MESSAGE_DEFAULT_LOGGEDIN + MESSAGE_DEFAULT_LOGGEDOFF,
        ],
    ],
];

Ключ массива — имя провайдера. Для него в языковом файле плагина нужна строка messageprovider:имя (например, messageprovider:debt_reminder): её увидят в настройках уведомлений. Блок defaults задаёт каналы, включённые по умолчанию. Значение MESSAGE_PERMITTED разрешает пользователю управлять каналом, а добавленные флаги определяют, включён ли он, когда пользователь на сайте и когда нет. Как и для других файлов в db/, после добавления нужно поднять версию и пройти обновление. Описание — в разделе Message API.

Отправка сообщения

$message = new \core\message\message();
$message->component         = 'local_example';
$message->name              = 'document_checked';
$message->userfrom          = \core_user::get_noreply_user();
$message->userto            = $user;
$message->subject           = 'Документ проверен';
$message->fullmessage       = 'Методист проверил ваш документ.';
$message->fullmessageformat = FORMAT_PLAIN;
$message->fullmessagehtml   = '<p>Методист проверил ваш документ.</p>';
$message->smallmessage      = 'Документ проверен';
$message->notification      = 1;
$message->contexturl        = (new \moodle_url('/local/example/documents.php'))->out(false);
$message->contexturlname    = 'Мои документы';

$messageid = message_send($message);

Поля, которые обязательно нужны: component, name, userfrom, userto, subject, fullmessage и формат. Остальные улучшают отображение. Короткая версия smallmessage показывается во всплывающем окне, полная HTML-версия идёт в письмо, а ссылка с названием превращается в кнопку «Подробнее». Если указать курс (courseid), сообщение привяжется к нему в отчётах.

Функция возвращает идентификатор сообщения; false означает, что отправить не удалось: например, получатель удалён, заблокирован или все каналы отключены. Это не всегда ошибка, проверяйте результат, но не считайте каждый false аварией.

Каналы доставки

КаналЧто делаетНа что смотреть
Popup (колокольчик)Показывает уведомление в интерфейсеПользователь видит его только при входе на сайт
EmailОтправляет письмоНастройка SMTP и репутации отправителя; подробности в статье о SMTP
Мобильное приложениеPush-уведомлениеРаботает при настроенном мобильном сервисе и регистрации устройства
Сторонние каналыПлагины типа message output для мессенджеровСовместимость с версией Moodle, хранение идентификатора пользователя в мессенджере

Администратор в разделе «Плагины → Исходящие сообщения → Настройки уведомлений» решает, какие каналы доступны и в каком режиме: запрещены, разрешены или принудительно включены. Пользователь после этого настраивает свои предпочтения в профиле. Из-за такой многоуровневой схемы одно и то же уведомление у разных пользователей приходит по-разному, и это нормально. Если же вам нужно, чтобы важное сообщение дошло в любом случае, просите администратора сделать для провайдера канал принудительным.

Уведомление или сообщение

У объекта есть поле notification. Единица означает системное уведомление: оно отображается в колокольчике и не подразумевает ответа. Ноль — личное сообщение, которое видно в мессенджере Moodle, и пользователь может на него ответить. Для автоматических писем плагина берите значение 1 и отправителя get_noreply_user(); личные сообщения от лица преподавателя или куратора — отдельный сценарий, и подставлять чужого пользователя в userfrom без его действия не стоит.

Когда отправлять не из запроса

Одно-два сообщения можно отправить сразу. Если нужно уведомить сотни слушателей (например, о начале сессии), отправку выносят в фоновую задачу: цикл по получателям в запросе пользователя может выполняться минутами и упереться в тайм-аут. Схема: действие или событие ставит adhoc-задачу, а задача перебирает адресатов и вызывает message_send() для каждого. Как писать такие задачи и находить зависшие, описано в статье про scheduled и adhoc tasks.

Для задач, повторяющихся ежедневно (напоминание о долгах, окончание обучения), добавьте защиту от дублей: храните в своей таблице отметку «уведомление отправлено» и сверяйтесь с ней. Иначе повторный запуск задачи после сбоя разошлёт сообщения повторно.

Тексты на языке получателя

Уведомление отправляется в контексте того, кто совершил действие, а читать его будет другой человек. Если куратор с русским интерфейсом закрыл заявку, а слушатель выбрал английский, строки нужно собрать на языке получателя. В Moodle для этого есть класс lang_string, который принимает язык четвёртым параметром, и функция принудительной смены текущего языка на время формирования текста. Забывать об этом легко: в тестах у всех один язык. Заведите в плагине единое место, где формируется текст сообщения для пользователя, и передавайте туда язык получателя из его профиля.

Отдельно поработайте с содержанием. Заголовок должен быть понятен без письма: «Документ проверен: справка о периоде обучения», а не «Уведомление». В полной версии пишите, что случилось и что делать дальше, и добавляйте ссылку через contexturl. Для HTML-версии используйте простую разметку: почтовые клиенты режут стили. Тексты, которые видят студенты, лучше согласовать с заказчиком, потому что они часто попадают в разбор жалоб.

Частота, отписка и согласие

Администратор может сделать провайдер принудительным, и тогда пользователь отключить канал не сможет. Для служебных сообщений о доступе, безопасности и обязательных сроках это оправдано. Для напоминаний, новостей и рассылок лучше оставить выбор за человеком: принудительная рассылка раздражает, а письма падают в спам, и репутация домена страдает у всех сообщений Moodle. Если сообщения содержат данные, относящиеся к человеку, учитывайте и требования по персональным данным. Для массовых информационных рассылок нужно согласие, и это надо решать на уровне процесса, а не кода.

Ограничивайте частоту. Если событие может сработать несколько раз подряд (преподаватель правит оценки по одной), отправляйте сводное сообщение через задачу с задержкой, а не десять писем за минуту. Простая схема: событие помечает пользователя в таблице «ждёт уведомления», а плановая задача раз в несколько минут собирает отметки и отправляет одно сообщение.

Свой канал доставки

Если заказчику нужны не письма, а, например, сообщения в мессенджере, добавляется плагин типа message output (каталог message/output). Его класс наследует базовый класс исходящих сообщений и реализует отправку одного сообщения, а также проверки: настроен ли канал на сайте и есть ли у пользователя нужный идентификатор (методы вроде is_system_configured() и is_user_configured()), и форму настроек пользователя. Идентификатор получателя во внешнем сервисе хранят в профильном поле или своей таблице. После установки канал появляется в настройках уведомлений рядом с почтой и всплывающим окном, и все провайдеры всех плагинов начинают работать через него без изменения кода. Бот в мессенджере и привязка аккаунта — отдельная часть работы: о ней в статьях про уведомления через Telegram и через MAX.

Поля объекта сообщения

ПолеНазначение
component, nameПлагин и провайдер из db/messages.php; по ним применяются настройки каналов
userfrom, usertoОтправитель (обычно системный) и получатель-пользователь
subjectТема письма и заголовок уведомления
fullmessage, fullmessageformatПолный текст и его формат (обычный текст, Markdown, HTML)
fullmessagehtmlHTML-версия для письма
smallmessageКороткая версия для всплывающего окна и мобильных каналов
notification1 для уведомления, 0 для личного сообщения
contexturl, contexturlnameСсылка на объект и её подпись
courseidПривязка сообщения к курсу

Из этой таблицы видно, где чаще всего ошибаются: забывают fullmessagehtml и получают письма из голого текста без абзацев, оставляют пустым smallmessage и видят в колокольчике обрезанный заголовок, или путают userfrom и userto и отправляют уведомление автору действия. Перед релизом отправьте себе по одному сообщению каждого провайдера по всем включённым каналам и посмотрите, как оно выглядит на экране телефона и в почтовом клиенте.

Проверка и тесты

Чтобы не отправлять реальные письма при тестировании, в PHPUnit используют перехватчики: $sink = $this->redirectMessages() перед действием, затем $sink->get_messages() возвращает всё, что было отправлено. Проверяйте получателя, провайдера и текст. На рабочем сайте для разовой проверки отправьте тестовое уведомление себе: если приходит во всплывающем окне, но не приходит письмом, проблема в SMTP, а не в вашем коде.

СимптомПричинаРешение
message_send вернул falseПолучатель удалён или приостановлен, каналы отключеныПроверить статус пользователя и настройки уведомлений
В настройках нет вашего типа уведомленийНе поднята версия после создания messages.phpОбновить плагин, очистить кэши
Название провайдера показывается как [[messageprovider:...]]Нет языковой строкиДобавить строку messageprovider:имя
Письма уходят, но в спамНастройки домена отправителяSPF, DKIM, корректный адрес отправителя

Если вам нужны уведомления студентам и кураторам по расписанию, статусам или оплатам, это типовая задача для доработки Moodle: описать сценарии, выбрать каналы и сделать защиту от дублей.

Нужна помощь с Moodle?

Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.