Много лет Moodle расширялся так: в lib.php плагина определяешь функцию с «правильным» именем, например local_example_before_footer(), и ядро находит её через get_plugins_with_function(). Работало, но ядру приходилось сканировать плагины, а разработчику — помнить сотню магических имён. Hooks API делает то же самое явно: ядро создаёт объект-хук, плагин заранее сообщает, что умеет его обработать, и получает объект в метод.
Как устроен хук
У хука три составляющие. Сам хук — класс в ядре или в плагине, который описывает, что именно можно дополнить. Обработчик — метод вашего класса, принимающий объект хука. И регистрация — файл db/hooks.php, где сказано, какой обработчик на какой хук подписан. Менеджер хуков (\core\hook\manager) собирает регистрации всех плагинов в один список при обновлении и потом быстро вызывает нужные методы, не обходя файлы.
Хуки бывают разные по назначению. Одни собирают вклад плагинов: «добавь свой HTML в шапку страницы». Другие позволяют остановить цепочку обработчиков, если это разрешает конкретный хук. Подробное описание и актуальный перечень приведены в разделе Hooks API на moodledev.io; список хуков ядра там же.
Сравнение с callback-функциями
| Что сравниваем | Callback в lib.php | Hooks API |
|---|---|---|
| Как ядро находит код | По имени функции в lib.php каждого плагина | По регистрации в db/hooks.php, собранной при обновлении |
| Как возвращает результат | Возвращаемое значение функции (строка, массив) | Вызывает методы объекта хука, например добавляет HTML |
| Загрузка кода | lib.php подключается целиком, даже если функция не нужна | Загружается только класс обработчика |
| Автозагрузка и тесты | Функция вне класса, тестировать неудобно | Обычный класс с автозагрузкой, обработчик можно вызвать в тесте |
| Приоритет | Порядок плагинов не регулируется | Есть параметр priority |
| Типизация | Свободная | Явный тип объекта хука в сигнатуре |
Главный практический выигрыш — загрузка. Раньше любой плагин с внушительным lib.php подключался на каждом запросе, где ядро искало callback. С хуками исполняется только то, на что подписались.
Пример: HTML в шапку страницы
Типичная задача — подключить на все страницы счётчик или маленький блок. Старый способ — функция в lib.php:
function local_example_before_standard_html_head() {
return '<meta name="example" content="1">';
}
Новый способ состоит из двух файлов. Регистрация в db/hooks.php:
defined('MOODLE_INTERNAL') || die();
$callbacks = [
[
'hook' => \core\hook\output\before_standard_head_html_generation::class,
'callback' => [\local_example\hook_callbacks::class, 'before_standard_head'],
'priority' => 0,
],
];
И обработчик в classes/hook_callbacks.php:
namespace local_example;
defined('MOODLE_INTERNAL') || die();
class hook_callbacks {
public static function before_standard_head(
\core\hook\output\before_standard_head_html_generation $hook
): void {
$hook->add_html('<meta name="example" content="1">');
}
}
Обратите внимание: обработчик ничего не возвращает, а добавляет вклад в объект. Это общий приём: хук собирает результат от нескольких плагинов, и каждый дописывает своё. Точное имя класса хука и его методов проверяйте в исходном коде вашей версии Moodle: описание каждого хука есть в комментариях его класса.
Как перенести плагин
- Найдите свои колбэки. Просмотрите
lib.phpи поищите функции, начинающиеся с имени компонента. В журнале с включённым режимом разработчика ядро показывает предупреждения «deprecated» с указанием хука-замены. - Сопоставьте с хуком. В документации и в каталоге
lib/classes/hookи*/classes/hookпосмотрите, какой хук приходит на смену вашей функции. - Перенесите логику в класс. Создайте
classes/hook_callbacks.php, в нём по статическому методу на хук. Сложный код вынесите в отдельные классы: обработчик должен только принять хук и вызвать сервис. - Зарегистрируйте. Заведите
db/hooks.php, поднимите версию вversion.php, пройдите обновление. - Уберите дубли. Если плагин рассчитан только на новые версии, удалите старую функцию. Если нужны и старые, оставьте её и убедитесь, что не получите двойной вывод.
- Проверьте на нескольких версиях и с включёнными предупреждениями.
Один плагин для нескольких версий
Если плагин должен жить и на 4.1 LTS, и на 4.5, и на 5.x, возможны два пути. Первый — ветки плагина под разные версии Moodle, это честнее всего и проще в сопровождении. Второй — совместимый код: в lib.php остаётся старая функция, в db/hooks.php — новая регистрация. В старых версиях файл hooks.php просто не читается, а новое ядро вызывает хук. Опасное место — версии, где ядро ещё вызывает и то, и другое. Тогда вывод задвоится, и приходится сравнивать версии через $CFG->branch или проверять существование класса хука.
Я обычно выбираю ветки, если расхождений больше одного-двух мест, и совместимый код — если плагин небольшой. Версии, с которыми я работаю, — от 3.10 до 5.x, и на практике парк клиентов почти всегда разнородный: с этим же сталкиваешься при обновлении Moodle, когда каждый сторонний плагин проверяют отдельно.
Типичные ошибки при миграции
| Симптом | Причина | Что делать |
|---|---|---|
| Обработчик не вызывается | Не поднята версия или не сброшены кэши | Поднять version.php, пройти обновление, очистить кэши |
| Fatal: class not found | Путь к классу не соответствует пространству имён | Положить файл в classes/ по правилам автозагрузки |
| HTML выводится дважды | Работают и старая функция, и новый обработчик | Убрать старую функцию или развести по версии |
| Предупреждения deprecated в логе | Остался вызов устаревшего API | Найти по тексту предупреждения замену и перенести |
| Обработчик ничего не добавляет | Результат возвращается через return, как в старом колбэке | Вызывать метод хука, а не возвращать значение |
Что в старых колбэках остаётся
Hooks API не отменил функции в lib.php целиком. Многие точки по-прежнему работают как классические callback-функции: выдача файлов (pluginfile), расширение навигации (extend_navigation_*), часть служебных обработчиков удаления и сброса. Мигрировать нужно те, которые ядро явно пометило устаревшими. Перед работой выпишите все функции плагина из lib.php и для каждой в документации и в коде ядра найдите ответ на один вопрос: объявлена ли она deprecated и какой хук указан в замену. Остальное не трогайте: преждевременный перенос не даёт ничего, кроме риска.
Свой хук в плагине
Механизм работает и в обратную сторону. Если ваш плагин сам предоставляет точку расширения (например, «до формирования ведомости» или «после проверки документа»), вы оформляете это как хук: заводите класс с данными, которые обработчики могут читать или изменять, описываете его назначение и теги и вызываете менеджер хуков, передав ему объект. Чужие плагины подписываются через свой db/hooks.php, и вам не нужно знать, сколько их и как они называются. Это чище, чем собственная система «вызвать все функции с таким-то именем». Точные атрибуты и интерфейсы для описания хука менялись между версиями, поэтому образцом берите ближайший по версии хук из ядра, а не пример из старых статей.
Практическое правило для обработчиков: они должны быть быстрыми и не бросать исключения по мелочам. Хук часто вызывается на каждой странице, и исключение в одном плагине ломает вывод всего сайта. Тяжёлые вещи выносите в сервисные классы с кэшем, а сам обработчик оставляйте тонкой оберткой. Проверить его просто: создаёте объект хука, вызываете метод обработчика напрямую и смотрите, что хук получил. Для этого и нужна вынесенная в класс логика: функцию из lib.php в таком виде тестировать куда неудобнее.
Хуки вывода: что к чему
Чаще всего плагинам нужны точки, связанные с выводом страницы. Ниже самые востребованные: имена классов сверяйте с каталогом хуков вашей версии Moodle.
| Хук | Что даёт плагину | Старый аналог |
|---|---|---|
\core\hook\output\before_standard_head_html_generation | Добавить HTML в секцию head страницы | Функция вида before_standard_html_head |
\core\hook\output\before_standard_top_of_body_html_generation | Добавить HTML в начало body | Функция вида before_standard_top_of_body_html |
\core\hook\output\before_footer_html_generation | Добавить HTML перед подвалом | Функция вида before_footer |
Случай из практики
При обновлении рабочей СДО центра ДПО с Moodle 4.3 до 5.2 через 4.5 LTS я проверяла каждый сторонний плагин, а не только его заявленную совместимость. Плагин может числиться совместимым и при этом работать на устаревших колбэках: страницы открываются, но журнал ошибок заполнен предупреждениями, а через версию-две такой код перестанет работать. Поэтому в чек-лист обновления я включаю отдельный шаг: прогнать основные сценарии с включённым режимом разработчика и выписать все предупреждения deprecated. Плагины, которые их порождают, получают заметку в плане: заменить, обновить или переписать обработчики по описанной выше схеме.
Когда события, когда хуки
Хуки не заменяют события. Если ваша задача — отреагировать на факт (завершён курс, создан пользователь), используйте события и наблюдатели. Хук нужен, когда ядро спрашивает у плагинов: что добавить в этом месте, что проверить, что поменять. Два механизма живут рядом, и в одном плагине их обычно используют вместе.
Если вам достался плагин с горой устаревших колбэков, который «перестал работать после обновления», это обычная задача для доработки Moodle: прочитать предупреждения, составить таблицу замен и перенести по одному колбэку с проверкой на целевых версиях.
Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.