Нужно отправить письмо, когда слушатель завершил курс, или записать в свою таблицу факт сдачи теста. Править ядро или модуль нельзя, а событие в этом месте уже есть: Moodle генерирует их на любое значимое действие. Задача плагина — подписаться на нужное и отреагировать. Ниже разобрано, как это устроено, что приходит в обработчик и где у подхода пределы.
Что такое событие в Moodle
Событие — объект класса, наследующего \core\event\base. Он описывает уже случившийся факт: пользователь создан, попытка теста отправлена, курс завершён. У события есть контекст, идентификатор объекта, пользователь-инициатор (userid), пользователь, к которому действие относится (relateduserid), и свободное поле other с дополнительными данными.
Одно и то же событие работает сразу в двух ролях. Во-первых, его пишут в журнал: на нём построены стандартные отчёты «Логи» и «Активность». Во-вторых, на него можно подписаться. Подробности — в разделе про Events API на moodledev.io.
Наблюдатель: файл db/events.php
Подписка описывается в файле db/events.php плагина. Это массив $observers, каждый элемент которого связывает имя события с методом-обработчиком.
defined('MOODLE_INTERNAL') || die();
$observers = [
[
'eventname' => '\core\event\course_completed',
'callback' => '\local_example\observer::course_completed',
],
];
Класс обработчика лежит в classes/observer.php. Метод статический и принимает объект события:
namespace local_example;
defined('MOODLE_INTERNAL') || die();
class observer {
public static function course_completed(\core\event\course_completed $event): void {
$userid = $event->relateduserid;
$courseid = $event->courseid;
// Лёгкая реакция: поставить задачу или записать строку в таблицу.
}
}
Для события завершения курса адресатом выступает relateduserid: инициатором (userid) может быть система, если завершение посчитал cron. Эту ошибку делают чаще других: берут userid и получают пустое значение или не того человека.
После правки events.php нужно поднять номер версии в version.php и пройти обновление, иначе список наблюдателей останется старым. Часть настроек элемента массива тоже важна:
| Параметр | Что делает |
|---|---|
eventname | Полное имя класса события с ведущим обратным слэшем |
callback | Статический метод или функция, которой передаётся событие |
includefile | Файл, который нужно подключить перед вызовом; для классов с автозагрузкой не нужен |
priority | Порядок вызова: чем больше число, тем раньше выполняется наблюдатель |
internal | По умолчанию true: наблюдатель вызывается сразу. При false вызов откладывается до фиксации транзакции, если событие сгенерировано внутри неё |
Значение internal => false стоит ставить, когда реакция не должна «видеть» откатываемые данные: например, вы отправляете письмо, а транзакция потом может быть отменена.
Какие события пригодятся чаще всего
Полный список событий ядра и модулей виден в интерфейсе: «Администрирование сайта → Отчёты → Список событий». Там же показаны уровень (edulevel), тип действия и поля, которые событие заполняет. Для типовых интеграций обычно хватает нескольких:
| Событие | Когда возникает | Зачем подписываться |
|---|---|---|
\core\event\user_created | Создан пользователь | Завести запись в своей таблице, отправить данные во внешнюю систему |
\core\event\user_enrolment_created | Пользователя записали на курс | Выдать доступ, создать группу, уведомить куратора |
\core\event\course_completed | Курс завершён пользователем | Сертификат, отчёт, смена статуса в зачётке |
\core\event\course_module_completion_updated | Изменилось состояние завершения элемента | Пересчитать собственные условия |
\mod_quiz\event\attempt_submitted | Попытка теста отправлена | Фиксировать результат, проверять правила допуска |
\core\event\user_graded | Изменилась итоговая оценка пользователя | Обновить выгрузку оценок |
Перед тем как писать код, найдите событие в списке и посмотрите, какие данные оно передаёт. Нередко нужная информация уже лежит в other и дополнительный запрос не нужен.
Свое событие: когда оно нужно
Если плагин совершает значимое действие (выдал документ, принял заявку, закрыл ведомость), стоит сгенерировать собственное событие. Это даёт два бонуса: действие попадает в журнал, а чужие плагины могут на него подписаться без правок вашего кода.
namespace local_example\event;
defined('MOODLE_INTERNAL') || die();
class request_approved extends \core\event\base {
protected function init() {
$this->data['crud'] = 'u';
$this->data['edulevel'] = self::LEVEL_OTHER;
$this->data['objecttable'] = 'local_example_request';
}
public static function get_name() {
return get_string('eventrequestapproved', 'local_example');
}
public function get_description() {
return "Пользователь с id {$this->userid} одобрил заявку {$this->objectid}.";
}
}
Отправка выглядит так:
$event = \local_example\event\request_approved::create([
'context' => \context_system::instance(),
'objectid' => $request->id,
'relateduserid' => $request->userid,
]);
$event->trigger();
Поле crud принимает одну из букв: c (создание), r (чтение), u (изменение), d (удаление). Уровень edulevel показывает, к кому относится действие: преподавание, участие в обучении или прочее. От этих полей зависят фильтры в отчёте логов. Если вы забудете init() или передадите неполные данные в create(), Moodle в режиме разработчика выбросит исключение с указанием, чего не хватает.
Название события хранится в языковом файле, а не в коде. Это пригодится, когда сайт многоязычный: в логах русскоязычный администратор увидит русский текст.
Чего нельзя ждать от наблюдателя
Наблюдатель получает уведомление, но не решает судьбу действия. Он не может запретить запись на курс или поменять оценку до сохранения: событие создаётся после того, как данные изменены. Если нужно вмешаться «по пути», то в одних местах это делают через хуки, в других — через собственные точки расширения подсистемы (например, проверки доступа и условия доступности).
Второе ограничение — время. Код наблюдателя работает в запросе пользователя. Если в нём вызывается внешний API, а тот отвечает за десять секунд, страница будет висеть десять секунд. Если упадёт исключение, оно прервёт действие, которое только что завершилось в основном коде. Поэтому правило простое: в наблюдателе проверить условие и поставить задачу в очередь, всё остальное сделать в adhoc-задаче.
Третье — порядок. Два плагина, подписанных на одно событие, выполняются по очереди, и рассчитывать на то, что чужой наблюдатель уже отработал, нельзя, если вы не управляете приоритетами. Данные, которые вам нужны, лучше читать из базы заново, а не из полей события: после чужой реакции они могли измениться.
События и хуки: как выбрать
| Вопрос | События (Events API) | Хуки (Hooks API) |
|---|---|---|
| Когда вызывается | После действия | Внутри процесса, когда ядро собирает данные или вывод |
| Может изменить результат | Нет | Да, через методы объекта хука |
| Попадает в журнал | Да | Нет |
| Типичный сценарий | Реакция: письмо, запись, синхронизация | Добавить блок в шапку, поправить вывод |
Про второй механизм я писала отдельно: Hooks API и миграция со старых callback-функций. Если задача звучит как «когда произойдёт Х, сделай Y», это события. Если «в таком-то месте добавь или поменяй Z» — хуки или колбэки подсистемы.
Как событие попадает в журнал
Каждое событие, у которого edulevel не помечен как «технический», записывается хранилищами журнала. По умолчанию работает стандартное хранилище, которое пишет строки в таблицу logstore_standard_log. На загруженном сайте эта таблица быстро становится самой большой в базе, и срок хранения записей настраивается отдельным параметром («Плагины → Журналы → Управление хранилищами журналов»). Поэтому не генерируйте событие на каждый чих: если плагин вызывает trigger() в цикле на тысячи записей, он раздует журнал и замедлит базу. Для массовых операций выпускайте одно событие с итогом.
Содержимое поля other сериализуется в JSON, значит, класть туда объекты нельзя: только скаляры и простые массивы. Если у вашего события есть обязательные данные, переопределите метод validate_data() и бросайте исключение при их отсутствии. Тогда ошибка вскроется на тесте, а не через полгода, когда кто-то откроет журнал и увидит пустые поля. Метод get_url() необязателен, но именно он превращает строку журнала в кликабельную ссылку на объект.
Журнал и наблюдатели не зависят друг от друга. Отключили запись журнала для уровня — наблюдатели всё равно получают событие. И наоборот, наблюдателя можно снять, а запись в журнале останется. Это полезно помнить, когда сайт арендуется у хостера с маленькой базой и админ режет журналы: бизнес-логика на событиях продолжает работать.
Частые ошибки наблюдателей
| Симптом | Причина | Что делать |
|---|---|---|
| Наблюдатель не вызывается | Не поднята версия после правки events.php или опечатка в имени события | Поднять версию, пройти обновление, сбросить кэши, сверить строку с классом |
| Пустой или чужой пользователь в обработчике | Берётся userid вместо relateduserid | Для действий «над» пользователем использовать relateduserid |
| Страница тормозит после действия | В наблюдателе тяжёлая работа или внешний запрос | Поставить adhoc-задачу и выйти |
| Действие пользователя завершилось ошибкой | Исключение в наблюдателе всплыло в основной код | Ловить исключения, писать в лог, не прерывать основной процесс |
| Реакция сработала дважды | Событие генерируется повторно или подписка объявлена в двух местах | Сделать обработку идемпотентной, проверить events.php |
| Реакция видит откатанные данные | internal равно true, а событие создано внутри транзакции | Поставить internal в false, чтобы вызов шёл после фиксации |
Отладка и тесты
Если наблюдатель молчит, пройдите по короткому списку:
- Откройте «Отчёты → Логи» и убедитесь, что событие вообще создаётся при вашем действии.
- Проверьте, что версия плагина поднята и обновление пройдено; после этого сбросьте кэши.
- Сверьте имя события и пространство имён: опечатка в строке не вызывает ошибки, подписка просто не работает.
- Убедитесь, что метод статический и его сигнатура принимает объект события.
- Если событие создаётся в транзакции и у вас
internal => false, наблюдатель сработает только после её фиксации.
В PHPUnit для проверки используют перехват событий: перед действием вызывают $sink = $this->redirectEvents(), а после читают $sink->get_events(). Это позволяет убедиться, что ваше событие сгенерировано один раз и с нужными полями. Сам observer тестируют как обычный класс, подавая ему подготовленный объект события.
Если у вас уже есть плагин, который нужно подключить к событиям ядра, или нужен новый модуль с чистой событийной архитектурой, начать можно со страницы про разработку плагинов Moodle.
Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.