Event System in OpenCart 4

OpenCartBot - 12 February 2023

CMS OpenCart 4.0 has a system of Events, which allows you to perform certain actions at certain moments of code execution. This allows you to extend the functionality of OpenCart without changing the source code.

When a certain event occurs, the event system calls all registered handlers for that event. Each handler can have its own code to handle this event.

OpenCart has built-in events like "catalog/view/common/header/before", "catalog/controller/product/product/before", "admin/controller/catalog/product/before" etc. You can use these events to change the behavior of OpenCart or add custom functionality.

OpenCart's event system allows you to create extensions that are easy to install and remove, making software development and maintenance much easier.

What is the difference between event and ocmod?

Event and ocmod are two different mechanisms for extending the functionality of OpenCart.

Event is used to react to certain events that occur in the system, for example, when a product is added to the cart or when an order is created. An event handler that has been registered in the system can perform certain actions when these events occur. Event does not change the core code of OpenCart, so its use is safe and does not affect the stability of the system.

ocmod, on the other hand, allows you to modify the core OpenCart code by applying patches to the existing code. This can affect the stability of the system, especially when updating the system to a new version. Using ocmod allows you to modify the core code of the system, so it has deeper capabilities to expand the functionality of the system.

The main difference between event and ocmod is that event allows you to react to events in the system, while ocmod allows you to modify the main code of the system. Both mechanisms have their advantages and disadvantages and should be used depending on the needs of the project and the circumstances. But in extension for OpenCart 4 ocmod is no longer supported, so starting from this branch you only need to use the event system (Events).

Advantages of Events:

A more flexible approach to code changes: When using the event system, you don't need to make changes to the main OpenCart code or install ocmod, which makes the extension more flexible and easier to develop and maintain.
Speed: The event system allows you to register an event handler and execute it when the event occurs, which can be faster than installing ocmod and editing files.
Compatibility: The event system generally remains compatible with previous versions of OpenCart, while ocmod may experience problems installing or running on different versions of OpenCart.
Ease of use: The event system allows developers to add new functionality or change the behavior of OpenCart without having significant experience in developing extensions.

The event system is useful in OpenCart for extending functionality and changing behavior without having to modify the OpenCart code or install ocmod. At the same time, ocmod can be useful for making deeper changes to the OpenCart code.

Disadvantages of Events:

Restrictions on modifying HTML: Using the event system, you cannot make changes to the HTML code of the page, which can be done using ocmod.
Complexity: Some types of events can be more complex to use, requiring advanced programming skills to develop and maintain.
Requires database access: The event system requires database access to register an event handler, which may pose some security issues.
May reduce performance: The event system may affect OpenCart's performance when executing event handlers, which may result in performance degradation.

Events-system has its limitations and disadvantages compared to ocmod, which can be useful for making deeper changes in the OpenCart code. But the event system is useful for extending functionality and changing behavior without having to modify the OpenCart code or install ocmod.

Creating an event handler in OpenCart 4

In OpenCart, an event handler or hook is a function that is automatically executed when a certain event occurs in the system. For example, when creating an order or adding a new product to the catalog.

In software programming and development, a hook is a mechanism that allows you to take action in a program or system by inserting specific code to perform specific functions at a specific point in the program's execution. Hooks can be used to connect additional functionality or to change the behavior of a program without changing the source code. For example, plugins for code editors can use Hooks to provide users with additional features such as code autocomplete, function hints, or additional information about the code structure.

In OpenCart hooks are called Events for some reason, and they are used to connect modules and extensions to different points of code execution of the platform. This allows you to extend the functionality of OpenCart and add new features without having to make changes to the main platform code. You can find the list of events in OpenCart 4 under Extensions > Events.

To create a hook, an event handler, you need to register it in the system. To do this, we create an array $event and pass it to the addEvent method. Up to and including OpenCart 4.0.1.1, the addEvent method required three arguments in the following sequence: $code, $trigger, $action.

So the $event array we are going to register must have the following elements:

'code' - the unique code of our hook
'trigger' - the trigger, the event
'action' - action, address of the event handler method
'description' - a short description of the hook
'sort_order' - the order in which the hook is launched
'status' - the status of the hook (enabled/disabled)

To clearly show how to create an event handler in OpenCart, we will give an example of adding your own code right after the <body> tag. So, we register the event handler:

$this->load->model('setting/event');
$event = [
 'code' => 'my_first_event',
 'trigger' => 'catalog/view/common/header/after',
 'action' => 'extension/opencartbot/module/my_module.myEventHandler',
 'description' => 'My first Event in OpenCart 4',
 'sort_order' => 1,
 'status' => true
];
$this->model_setting_event->addEvent($event);

After registering the hook, we will see it in the Events list in the admin and can view it. It looks like this:

Now, in the controller file of our module, we add a method to handle the event:

public function myEventHandler(string &$route, array &$data, mixed &$output): void {
 $module = $this->load->view('extension/opencartbot/module/my_module', $data);
 $output = str_replace('<body>',  '<body>' . $module,  $output);
}

The list of possible arguments that are passed to the method and their explanations:

&$route - contains data about the path of this event;
&$data - contains an array of data for the operation of the event, for example, for view files, this is data that is transferred from the controller to the view
&$output - contains the result of the event, for view files - it is the content of the twig template

For controller, model, view, language, the set of arguments passed to the handler is the same. But the list of arguments varies depending on the type of event:

with before: &$route, &$data
when after: &$route, &$data, &$output

That is, if our handler reacts before the /before event, then the handler will look like this:

public function myEventHandler(string &$route, array &$data): void {
 $data['my_param'] = 'My value;'
}

Example of deleting an event handler:

$this->load->model('setting/event');
$this->model_setting_event->deleteEventByCode('my_first_event');

To check the presence of an event handler in the system, you can use the following code:

$this->load->model('setting/event');
if ($this->model_setting_event->getEventByCode('my_first_event')) {
 // The event exists
} else {
 // The event does not exist
}

Of course, this is just basic information about the OpenCart 4.0 event system. But thanks to it, you can understand the principle of operation in order to perform more complex operations.