Хуки и события в Drupal: типичные ошибки и как их избежать

В Drupal 10 и 11 обработчик может не сработать не потому, что его «не заметил» Drupal, а потому что он назван не по имени модуля, не зарегистрирован как сервис или подписан не на то событие. А если логика запускается и в хуке, и в подписчике, результат способен выполниться дважды. Ниже — типичные ошибки при работе с хуками и событиями и способы их избежать.

Сначала выберите механизм

Хуки — механизм Drupal: модуль реализует функцию с именем, предусмотренным API. Через хуки модуль подключается к конкретным точкам расширения Drupal или меняет данные, которые формирует система. События — механизм Symfony: компонент публикует событие, а подписчик, зарегистрированный как сервис, реагирует на него. Они пересекаются по назначению, но не взаимозаменяемы.

Не выбирайте событие только потому, что оно кажется «современнее». Для изменения формы или данных сущности сначала проверьте, есть ли предназначенный для этого хук. Для реакции на событие жизненного цикла запроса или другой компонент Symfony — проверьте документацию именно к нужному событию.

Ошибки в хуках

Имя функции не соответствует модулю

Drupal ищет реализацию по имени, которое складывается из имени модуля и имени хука. Для модуля example реализация hook_entity_presave() называется example_entity_presave(). Файл с функцией обычно размещают в корне модуля, например example.module. Опечатка в префиксе или суффиксе означает, что обработчик не будет вызван.

Проверьте машинное имя каталога и модуля, точное имя хука в документации версии Drupal и расположение функции. Не ориентируйтесь на имя, которое видите в интерфейсе: машинное имя может отличаться от читаемого.

Хук работает не в том месте

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

Ещё одна ловушка — повторные побочные эффекты. Сохранение сущности может происходить несколько раз в рамках одного пользовательского сценария. Если обработчик каждый раз отправляет письмо или создаёт внешнюю запись, пользователь получит дубликаты. Отделяйте подготовку данных от необратимых действий и продумывайте идемпотентность¹.

Изменяют данные не тем способом

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

Для отладки временно записывайте в лог вход в обработчик и ключевые параметры, но не выводите чувствительные данные. После проверки удалите шумные сообщения. Очистите кэш Drupal и убедитесь, что модуль включён: иначе вы будете диагностировать код, который система ещё не подхватила.

Ошибки в подписчиках событий

Класс есть, подписчика нет

Само наличие PHP-класса не делает его подписчиком. Для стандартного Symfony-подхода класс реализует EventSubscriberInterface, объявляет, на какие события реагирует, а сервис модуля получает тег event_subscriber. Если пропустить регистрацию в YAML, обработчик не подключится.

После изменения конфигурации очистите кэш, затем проверьте журнал ошибок и контейнер сервисов. Если класс не загружается, проверьте пространство имён и путь файла. Если сервис зарегистрирован, но метод не вызывается, сравните имя события с документацией той версии Drupal или компонента Symfony, которая установлена в проекте.

Событие выбрано по названию, а не по смыслу

Два события с похожими именами могут происходить на разных этапах. Подписчик на событие запроса не обязательно подходит для изменения ответа, а событие Symfony не заменяет любой Drupal-хук. Проверьте, кто именно отправляет событие, когда оно отправляется и какие данные доступны обработчику.

События с высоким приоритетом могут выполниться раньше других подписчиков. Не задавайте приоритет наугад: сначала выясните, кто ещё реагирует на это событие и важен ли порядок. Иначе результат может зависеть от стороннего модуля или обновления конфигурации.

Проверка перед выпуском

1. Зафиксируйте ожидаемый момент. Запишите действие пользователя или системный процесс, после которого должна запускаться логика. Проверка: команда воспроизводится одинаково на тестовой среде.
2. Найдите точку расширения для своей версии. Сверьте имя, аргументы и назначение в официальной документации. Проверка: сигнатура вашего обработчика совпадает с описанием.
3. Проверьте подключение. Для хука проверьте имя функции и файл модуля; для события — интерфейс подписчика, метод подписки и регистрацию сервиса. Проверка: после очистки кэша обработчик появляется в журнале при ожидаемом действии.
4. Проверьте повторный запуск. Повторите действие, импортируйте данные или запустите пакетную операцию, если это относится к вашему сценарию. Проверка: письма, записи и внешние запросы не дублируются.
5. Проверьте отказ внешней зависимости. Если обработчик обращается к API или очереди, временно проверьте ошибочный ответ. Проверка: ошибка фиксируется, а сохранение данных не приводит к скрытому частичному результату.

Что ломается в продакшене

Самые дорогие ошибки — не синтаксические, а поведенческие. Обработчик может запускаться при пакетном импорте, где внешнее API отвечает медленно; повторно срабатывать при сохранении; или менять данные, от которых зависит другой подписчик. Локальный тест на одном объекте этого не покажет.

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

Если обработчик нельзя безопасно запустить повторно, проблема не только в выборе хука или события. Это риск повторной отправки, импорта или сохранения — и его нужно решать на уровне самой операции.

¹ Идемпотентность — свойство операции, при котором повторный запуск с теми же данными не создаёт лишних изменений или побочных эффектов.

Что делать дальше

Составьте для каждого обработчика короткую карточку: что его запускает, какие данные он меняет, может ли выполниться повторно и что произойдёт при ошибке зависимости. Затем добавьте тест на основной сценарий и отдельно проверьте повторный запуск. Если выбираете между хуком и событием, начните с документации Drupal для установленной версии, а не с примера из старого модуля.