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

Hooks API в Moodle 4.4+: чем отличается от старых callback-функций и как мигрировать

Hooks API в Moodle: как он заменяет функции-колбэки в lib.php, как регистрировать обработчики в db/hooks.php и как перенести старый плагин без поломок.

Hooks API в Moodle: как он заменяет функции-колбэки в lib.php, как регистрировать обработчики в db/hooks.php и как перенести старый плагин без поломок.

Много лет 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.phpHooks 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: описание каждого хука есть в комментариях его класса.

Как перенести плагин

  1. Найдите свои колбэки. Просмотрите lib.php и поищите функции, начинающиеся с имени компонента. В журнале с включённым режимом разработчика ядро показывает предупреждения «deprecated» с указанием хука-замены.
  2. Сопоставьте с хуком. В документации и в каталоге lib/classes/hook и */classes/hook посмотрите, какой хук приходит на смену вашей функции.
  3. Перенесите логику в класс. Создайте classes/hook_callbacks.php, в нём по статическому методу на хук. Сложный код вынесите в отдельные классы: обработчик должен только принять хук и вызвать сервис.
  4. Зарегистрируйте. Заведите db/hooks.php, поднимите версию в version.php, пройдите обновление.
  5. Уберите дубли. Если плагин рассчитан только на новые версии, удалите старую функцию. Если нужны и старые, оставьте её и убедитесь, что не получите двойной вывод.
  6. Проверьте на нескольких версиях и с включёнными предупреждениями.

Один плагин для нескольких версий

Если плагин должен жить и на 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: прочитать предупреждения, составить таблицу замен и перенести по одному колбэку с проверкой на целевых версиях.

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

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