The Events system in OpenCart 4

OpenCart 4.0 CMS has an Events system that allows you to perform specific actions at certain moments of code execution. This makes it possible to extend OpenCart functionality without modifying 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 for processing that event.

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

OpenCart's event system allows you to create extensions that are easy to install and remove, which significantly simplifies the development and maintenance of the software.

What is the difference between event and ocmod?

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

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

ocmod, on the other hand, allows you to modify the OpenCart core code by applying patches to existing code. This can affect system stability, 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 for extending system functionality.

The main difference between event and ocmod is that events allow you to react to events in the system, whereas ocmod allows you to modify the core code of the system. Both mechanisms have their advantages and disadvantages and should be used depending on project needs and circumstances. However, in OpenCart 4 modules ocmod is no longer supported, so starting from this branch you must use only the Events system. 

Advantages of Events:

1. A more flexible approach to code changes: when using the events system, you do not need to make changes to the OpenCart core code or install an ocmod, which makes the extension more flexible and convenient to develop and maintain.
2. Speed: the events system allows you to register an event handler and execute it when the event occurs, which can be faster than installing an ocmod and reworking files.
3. Compatibility: the events system usually maintains compatibility with previous OpenCart versions, whereas ocmod may run into problems with installation or operation on different OpenCart versions.
4. Ease of use: the events system allows developers to add new functionality or change OpenCart's behavior without having significant experience in extension development.

The events system is useful in OpenCart for extending functionality and changing behavior without the need to make changes to the OpenCart code or install an ocmod. At the same time, ocmod can be useful for performing deeper changes to the OpenCart code.

Disadvantages of Events:

1. Limitations on HTML modifications: using the events system you cannot make changes to the page's HTML code, which can be done with ocmod.
2. Complexity: some types of events can be more complex to use, requiring strong programming skills for development and maintenance.
3. Requires database access: the events system requires database access to register an event handler, which can create certain security concerns.
4. May reduce performance: the events system can impact OpenCart performance when executing event handlers, which may lead to slower operation.

The Events system has its limitations and disadvantages compared to ocmod, which can be useful for performing deeper changes to OpenCart code. But the events system is useful for extending functionality and changing behavior without the need to make changes to the OpenCart code or install an 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 an order is created or a new product is added to the catalog.

In programming and software development, a hook is a mechanism that allows you to intervene in the operation of a program or system by inserting certain code to execute specific functions at a certain point of the program's execution. Hooks can be used to plug in additional functionality or to change a program's behavior without modifying the source code. For example, plugins for code editors may use hooks to provide users with additional features such as code autocompletion, function hints, or extra information about code structure.

In OpenCart, hooks are for some reason called Events; they are used to plug modules and extensions into different points of code execution within the platform. This allows extending OpenCart functionality and adding new features without the need to make changes to the platform's core code. You can find the list of events in OpenCart 4 in the Extensions > Events section.

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

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

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

To clearly show how to create an event handler in OpenCart, let's give an example of adding our own code right after the 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/ocdev.pro/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 panel and will be able to view it. It looks like this:

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

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

The list of possible arguments passed to the method and explanations of them:

• &$route - contains data about the path of this event;
• &$data - contains the data array for the event's operation; for view files this is the data passed from controller to view
• &$output - contains the result of the event's work; for view files this is the contents of the Twig template

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

• for before: &$route, &$data
• for after: &$route, &$data, &$output

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

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

An example of removing an event handler:

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

To check whether an event handler is present 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 is registered in the system
} else {
 // The event is missing
}

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