Хуки и события в Drupal: чек-лист перед продакшеном

Что проверить до выкладки

В Drupal 10 и 11 один неверно выбранный хук или подписчик события может задержать сохранение сущности, отправить письмо дважды или сделать страницу невидимой для кеша. Перед релизом проверьте не только, что обработчик вызывается, но и когда он вызывается, что меняет и как ведёт себя при повторном запуске.

Этот чек-лист подходит разработчику, который уже добавил hook или Symfony event subscriber и готовит модуль к выпуску. Он не заменяет тестирование конкретного бизнес-сценария: имена событий, аргументы и момент вызова зависят от выбранного API и версии Drupal.

Сначала определите, кто вызывает ваш код

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

Подписчик события¹ — сервис, который объявляет интерес к определённым событиям и выполняет код, когда диспетчер их отправляет. Это не то же самое, что hook: регистрации и правила вызова различаются.

Чек-лист перед релизом

1. Зафиксируйте целевые версии. Укажите Drupal 10 или 11, версии PHP и зависимых модулей, на которых вы проверяли изменение. Сверьте сигнатуру hook, класс события и доступные методы с документацией именно этой ветки. Проверка только на локальной копии другой версии не подтверждает совместимость. Готово, если версия и ограничения записаны в задаче или документации модуля.
2. Проверьте точку вызова. Найдите, кто именно вызывает hook или отправляет событие и на каком этапе. Уточните, какие данные уже доступны, а какие ещё не сохранены. Не полагайтесь на название вроде «после сохранения»: подтвердите порядок по документации или исходному коду установленной версии. Готово, если тест воспроизводит нужный этап жизненного цикла.
3. Убедитесь, что обработчик зарегистрирован. Для hook проверьте имя функции и имя модуля; для subscriber — сервис, класс и объявленные события. После изменения сервисной конфигурации очистите кеши Drupal штатными средствами проекта. Готово, если автоматический тест или проверка в тестовой среде подтверждает вызов именно этого обработчика.
4. Проверьте порядок и конфликты. В проекте могут быть другие модули, которые слушают тот же hook или событие. Посмотрите, зависит ли результат от порядка исполнения и есть ли у системы приоритеты или правила изменения данных. Если порядок важен, зафиксируйте это тестом, а не предположением. Готово, если результат остаётся корректным при включённых зависимостях проекта.
5. Сделайте обработчик безопасным при повторном вызове. Некоторые операции могут запускаться повторно из-за повторной попытки, очереди или нескольких путей обновления данных. Если обработчик создаёт запись, отправляет уведомление или запускает внешнее действие, предусмотрите защиту от дубликатов там, где она нужна. Готово, если повторный запуск не создаёт нежелательных побочных эффектов.
6. Разделите изменение данных и внешние действия. Не отправляйте письмо или запрос к внешнему сервису бездумно внутри обработчика сохранения: сбой внешней системы может повлиять на пользовательский запрос. Проверьте, уместна ли очередь, и определите, что произойдёт при ошибке или повторе задания. Готово, если отказ внешней зависимости не приводит к потере данных или незаметному повтору действия.
7. Проверьте кеш и доступ. Если код меняет отображаемые данные, убедитесь, что изменения учитывают кеширование Drupal и права доступа. Для рендеримого результата важны корректные cache contexts, tags и max-age; отсутствие нужной зависимости может показать одному пользователю чужие или устаревшие данные. Готово, если проверка проходит для разных ролей и после очистки либо обновления связанных кешей.
8. Добавьте тест и наблюдаемость. Покройте ожидаемый результат и хотя бы один отрицательный сценарий: неподходящий тип сущности, отсутствие необязательных данных или ошибку внешней зависимости. Логируйте контекст, достаточный для диагностики, но не записывайте секреты и персональные данные без необходимости. Готово, если сбой можно найти по журналам, а тест ловит поломку до выкладки.

Где ломается очевидный подход

Частая ошибка — поместить всю бизнес-логику в один hook или subscriber. Тогда обработчик становится зависимым от деталей Drupal, а его побочные эффекты трудно проверить отдельно. Оставьте в точке расширения короткий вызов сервиса, а правила вынесите в отдельный класс, который можно тестировать без полного сценария запроса.

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

Перед релизом важнее ответить не на вопрос «вызывается ли обработчик», а на вопрос «что произойдёт, если он вызовется ещё раз, позже или при сбое зависимости».

Ещё одна ловушка — тестировать только пользователя с административными правами. Такой тест не обнаружит ошибку в доступе или кешировании, которая проявится у посетителя сайта. Проверяйте результат с теми ролями и условиями, для которых написана логика.

Когда задача не закрыта

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

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

¹ Диспетчер событий — компонент, который принимает событие и передаёт его зарегистрированным слушателям или подписчикам.

Версии и API сверяйте по документации Drupal для конкретной ветки: Drupal 10 и Drupal 11 могут отличаться требованиями к окружению и зависимостям, а contrib-модуль — поддерживаемыми версиями отдельно.