ave-cms/help/hooks/catalog.md

Каталог системных событий

← К разделу «Хуки и события»

HookCatalog хранит стабильные точки расширения, их назначение, контекст и источник. Модули могут добавлять определения через hook_definitions; runtime также отмечает фактически вызванные динамические хуки.

Если в таблице не указано иное, контекст — App\Common\LifecycleEvent.

Система и модули

Событие	Назначение
system.initialize	Системный runtime инициализирован.
module.registered	Descriptor зарегистрирован; контекст — строковый код.
module.installed	Установка завершена.
module.updated	Обновление завершено.
module.enabled, module.disabled	Состояние активности изменено.
module.uninstalling, module.uninstalled	До и после деинсталляции.

Публичный HTTP-запрос

Событие	Назначение
frontend.request.received	Получен публичный запрос.
frontend.runtime.ready	Конфигурация и публичные модули загружены.
frontend.route.resolved	Определён маршрут и контекст страницы.
frontend.response.rendering	Ответ подготовлен перед финальной выдачей.
frontend.response.rendered	Финальный HTML сформирован.

Документы и рубрики

Событие	Назначение
content.document.loading, content.document.loaded	До и после чтения документа.
content.document.saving, content.document.saved	До и после сохранения; DocumentSaveEvent.
content.document.created, content.document.updated	Создание/обновление; DocumentSaveEvent.
content.document.published, content.document.unpublished	Смена публикации; DocumentSaveEvent.
content.document.deleting, content.document.deleted	До и после удаления.
content.document.snapshot_built	Итоговый JSON-снимок перестроен.
content.rubric.loading, content.rubric.loaded	До и после чтения рубрики.
content.rubric.schema_impact	Дополняет список зависимостей перед восстановлением схемы рубрики; контекст — массив.

Фильтр content.rubric.schema_impact получает rubric_id, field_ids, описания полей в fields и массив items. Модуль добавляет в items записи с ключами key, title, meta, details и возвращает весь контекст. Анализ ничего не изменяет в БД и не должен выполнять тяжёлые пересчёты: его результат входит в fingerprint подтверждения восстановления.

Сам движок всегда добавляет в анализ JSON API документов: его чтение и запись используют alias, ID, тип и структуру значения поля. Для запросов отдельно проверяются условия, сортировка, шаблонные теги и контракт результата. Из установленных подсистем учитываются каталоги, варианты товаров и товарные фиды.

Запросы, шаблоны и блоки

Событие	Назначение
content.query.loading, content.query.loaded	Чтение AVE-запроса.
content.query.rendering, content.query.rendered	Рендер списка/запроса.
content.template.loading, content.template.loaded	Чтение шаблона страницы.
content.template.rendering, content.template.rendered	Выполнение шаблона страницы.
content.block.rendering, content.block.rendered	Совместимый вызов блока через старый тег block.
content.sysblock.loading, content.sysblock.loaded	Чтение блока из единого реестра.
content.sysblock.rendering, content.sysblock.rendered	Основной цикл рендера блока.

Поля

Событие	Назначение
content.field.registry	Реестр типов собран.
content.field.normalizing, content.field.normalized	Нормализация значения.
content.field.validating, content.field.validated	Серверная валидация.
content.field.saving, content.field.saved	Запись значения.
content.field.rendering, content.field.rendered	Публичный вывод.

Точный набор ключей описан в Хуках полей.

Пользователи

Событие	Назначение
auth.user.registering, auth.user.registered	До и после регистрации публичного пользователя.
auth.user.authenticated	Успешный вход.
auth.user.logged_out	Выход.
auth.phone.code_sent	Код передан SMS-провайдеру; доступны код провайдера и маскированный телефон, но не сам код.

Commerce

Commerce-события доступны, когда установлен соответствующий пакет.

Событие	Назначение
commerce.cart.changed	Состав корзины изменён.
commerce.order.creating, commerce.order.created	До и после создания заказа.
commerce.order.status_changed	Статус заказа изменён.
commerce.payment.completed	Платёж подтверждён.
commerce.delivery.quoted	Получен расчёт доставки.

Товарный каталог

Фильтр	Назначение
catalog.product_cards.rendering	Передаёт место вывода, ID товаров и исходный HTML. Обработчик может вернуть центральные карточки и handled=true.

Контекст фильтра: context, product_ids, items, html, handled. Товарный модуль захватывает вывод только для контекста, явно переведённого в режим центральной карточки. Если хотя бы один документ отсутствует в товарном индексе, исходный HTML сохраняется.

Кеш

Событие	Назначение
cache.invalidating	Перед удалением ключа, тега или всего кеша.
cache.invalidated	После завершения очистки.

Загрузка файлов

Эти хуки используют массив, а не LifecycleEvent.

Событие	Назначение
file.upload.validating	Фильтр до сохранения. Получает allowed, reason, temporary_path, original_name, size, destination, source.
file.upload.stored	Файл сохранён; получает итоговый path, исходное имя, размер и источник.

Ядро всегда отклоняет служебные файлы сервера, неоднозначные имена, исполняемые и активные веб-форматы, включая SVG. Для известных источников также проверяются допустимые расширения и сигнатуры содержимого. Модуль может дополнительно ужесточить правила: для этого фильтр возвращает весь массив с allowed=false и понятным текстом в reason. Вернуть ядром запрещённый формат через hook нельзя.

Как узнать фактический контекст

Каталог описывает класс контекста и назначение события. Конкретные ключи LifecycleEvent::data() зависят от операции. На тестовом стенде включите публичный отладчик, откройте вкладку Хуки и сопоставьте событие с вкладками документа, SQL и timeline. Не выводите весь контекст посетителю и не логируйте секреты авторизации.

Обращения по товарам

После создания уведомления о поступлении, предзаказа или запроса цены модуль products вызывает catalog.product.demand.created. Событие подходит для подключения CRM, мессенджера или собственного канала уведомлений.

Контекст содержит type, document_id и public_user_id. Контактные данные намеренно не передаются в публичный каталог hook-ов: модуль с соответствующими правами читает полную запись через DemandRepository.

Личный кабинет расширяется фильтрами auth.account.links и auth.account.overview. Первый добавляет ссылки, второй — краткие карточки на обзорную страницу.