# Отладка и надёжность хуков

← [К разделу «Хуки и события»](README.md)

## Вкладка публичного отладчика

Для авторизованного администратора публичный Debug Toolbar показывает вкладку
**Хуки**. В ней видны:

- имя и тип вызова (`action`/`filter`);
- обработчик и priority;
- длительность;
- статус и исключение;
- количество вызовов и вложенность.

Trace включается только вместе с защищённым отладчиком и ограничен 1500
обработчиками на запрос. Превышение отображается как отброшенные записи, чтобы
сама диагностика не исчерпала память.

Включение панели и вывод собственных значений через `Debug::panel()` описаны в
[разделе «Публичная отладка»](../debug/README.md).

## Диагностика обработчика

1. Убедитесь, что модуль установлен и включён.
2. Проверьте, в какой секции объявлен hook: `admin`, `public` или верхний уровень.
3. Проверьте имя события и namespace класса.
4. Посмотрите вкладку **Хуки**: был ли вызов и какой обработчик выполнился.
5. Сопоставьте время с SQL/HTTP/timeline.
6. Проверьте фильтрацию по type/rubric/source внутри обработчика.

`Hooks::exists()`, `has()` и `current()` подходят для локальной диагностики.
`Hooks::debug()` печатает HTML и не должен использоваться в production-коде;
для структурированных значений используйте защищённую панель отладки.

## Исключения

Обычный `Hooks::action()` и `filter()` пробрасывают исключение вызывающему коду.
Поведение конкретной lifecycle-точки может быть строже:

- ошибка/`fail()` в `content.document.saving` отклоняет сохранение;
- исключение в after-событии документа журналируется, но commit не откатывается;
- ошибка в рендеринге может остановить публичный ответ.

Ловите только ожидаемые ошибки. Не скрывайте исключение пустым `catch`: запишите
контекст без секретов и дайте операции контролируемый статус повтора.

## Производительность

- Не выполняйте одинаковый SQL на каждое поле или элемент списка.
- Не очищайте весь кеш, если известен тег или ключ сущности.
- Не вызывайте внешний HTTP в транзакции сохранения.
- Для интеграций используйте outbox, идемпотентный ключ и ограниченный web-runner.
- Обработчик должен быстро завершаться, если событие относится не к его рубрике,
  типу или операции.

## Безопасность

Контекст может содержать пользовательские данные, HTML, email и служебные
идентификаторы. Не передавайте его целиком внешнему сервису, не записывайте
пароли/токены в лог и экранируйте результат, если hook возвращает HTML.