Events: triggers and registration

An event is a way to run your code at a certain moment of the core's work without editing core files. The engine sends a signal before and after every call of a controller, a model method and a template. An extension registers a handler for the signal it needs.

The trigger

A trigger is the name of the signal. It is assembled from four parts:

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

The path may contain an asterisk: catalog/view/*/before fires for every template.

The handler

A handler is a public method of a controller in your extension. Add it to the storefront controller of the module:

// extension/acme_hello/catalog/controller/module/acme_hello.php
public function productOpened(string &$route, array &$args): void
{
    $this->log->write('Product page opened: ' . (int) ($this->request->get['product_id'] ?? 0));
}

The method writes a line to the error log every time the product page is opened.

Registration

The link between the trigger and the handler is stored in the database. It is added in install() of the admin controller and removed in 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' => 'Logs product page views',
        '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');
}

In releases 4.0.0 and 4.0.1 addEvent() took these values as separate arguments instead of an array — check the method in admin/model/setting/event.php of your copy.

Checking

Reinstall the module: Uninstall, then Install in Extensions → Extensions → Modules. The event appears in the list Extensions → Events — there it can be turned off and on.

Open any product on the storefront, for example index.php?route=product/product&product_id=42, then System → Maintenance → Error Logs in the admin panel. The log contains the line «Product page opened: 42».

Common mistake

The trigger is written with a mistake — a wrong folder, addhistory instead of addHistory, a missing catalog/ at the start. There is no error: the handler is simply never called. Compare the trigger with the path of the real file and the name of the method letter by letter, and check that the event is enabled in Extensions → Events.