Уведомление из плагина — это не просто 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 (колокольчик) | Показывает уведомление в интерфейсе | Пользователь видит его только при входе на сайт |
| Отправляет письмо | Настройка 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) |
fullmessagehtml | HTML-версия для письма |
smallmessage | Короткая версия для всплывающего окна и мобильных каналов |
notification | 1 для уведомления, 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: описать сценарии, выбрать каналы и сделать защиту от дублей.
Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.