События: триггеры и регистрация

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

Триггер

Триггер — имя сигнала. Оно складывается из четырёх частей:

catalog/controller/product/product/before
catalog/model/checkout/order.addHistory/after
admin/view/catalog/product_form/before

Часть	Значения
Приложение	`catalog` или `admin`
Вид	`controller`, `model`, `view`, `language`, `config`
Путь	Маршрут и, через точку, метод
Момент	`before` или `after`

В пути можно использовать звёздочку: catalog/view/*/before срабатывает для любого шаблона.

Обработчик

Обработчик — открытый метод контроллера в вашем дополнении. Добавьте его в контроллер витрины модуля:

// extension/acme_hello/catalog/controller/module/acme_hello.php
public function productOpened(string &$route, array &$args): void
{
    $this->log->write('Открыта страница товара: ' . (int) ($this->request->get['product_id'] ?? 0));
}

Метод пишет строку в журнал ошибок каждый раз, когда открывают страницу товара.

Регистрация

Связь триггера с обработчиком хранится в базе. Её добавляют в install() контроллера панели и удаляют в uninstall():

// extension/acme_hello/admin/controller/module/acme_hello.php
public function install(): void
{
    $this->load->model('setting/event');
 
    $this->model_setting_event->addEvent([
        'code' => 'acme_hello_product',
        'description' => 'Записывает просмотры страниц товаров',
        'trigger' => 'catalog/controller/product/product/before',
        'action' => 'extension/acme_hello/module/acme_hello.productOpened',
        'status' => true,
        'sort_order' => 1,
    ]);
}
 
public function uninstall(): void
{
    $this->load->model('setting/event');
 
    $this->model_setting_event->deleteEventByCode('acme_hello_product');
}

Ключ	Смысл
`code`	Уникальное имя события, по нему его удаляют
`trigger`	Сигнал, который нужно слушать
`action`	Маршрут и метод обработчика
`status`	Включено ли событие
`sort_order`	Порядок среди обработчиков одного триггера

В выпусках 4.0.0 и 4.0.1 addEvent() принимал эти значения отдельными аргументами, а не массивом — проверьте метод в admin/model/setting/event.php своей копии.

Проверка

Переустановите модуль: Uninstall, затем Install в Extensions → Extensions → Modules. Событие появится в списке Extensions → Events — там его можно выключить и включить.

Откройте на витрине любой товар, например index.php?route=product/product&product_id=42, а затем в панели — System → Maintenance → Error Logs. В журнале есть строка «Открыта страница товара: 42».

Частая ошибка

Триггер написан с ошибкой — не та папка, addhistory вместо addHistory, пропущено catalog/ в начале. Ошибки не будет: обработчик просто никогда не вызовется. Сверьте триггер с путём настоящего файла и именем метода буква в букву и убедитесь, что событие включено в Extensions → Events.

Спасибо, что читаете!