Ka Extensions vs OpenCart events: speed and convenience

OpenCart 3 has several ways to change store behaviour without editing the core. This article compares two of them:

  • OpenCart events. This is the built-in mechanism. A module registers a handler for a route such as admin/model/catalog/product/addProduct/before, and OpenCart calls it before or after that method.
  • Inheritance with Ka Extensions (kamod). A module adds a class that extends the original OpenCart class and overrides the method it needs. Kamod builds an inheritance chain from these classes, and the original code is reached through parent::.
We deliberately leave OCMOD out of this comparison. OCMOD is a good tool, but it patches the text of core files by search and replace. On large stores with many modules these patches become hard to maintain, so on large projects it is better to avoid OCMOD.

The two mechanisms are compared on the same code, first for convenience and then for speed. All measurements are given as a change in percent against plain OpenCart, with absolute values in parentheses. Red numbers mean extra cost, green numbers mean no extra cost.

Summary

What is compared OpenCart events Ka Extensions
How a module hooks in a handler controller receives the $args array by reference a normal PHP method with the same parameters as the original
Parameters positional: $args[0], $args[1]… You have to check the core to see what each index holds named: $data, $product_id
10 modules, product page +17% (+4.1 ms) + 1%
50 modules (forecast), product page +83…96% (+20…24 ms) on the test page + 3%
Minimum files of a module installer controller with handlers, plus records in the oc_event table kamod.ini, active.kamod and the class that overrides the method
Module order event sort_order install_before / install_after in kamod.ini
Several modules on one method yes yes, as a chain through parent::

Example: changing a product field on save

Task: when a product is saved in the admin, convert its model field to upper case. Both addProduct() and editProduct() have to be intercepted.

With OpenCart 3 events

File admin/controller/extension/module/upper_model.php, holding both the installer and the handlers:

PHP
<?php
class ControllerExtensionModuleUpperModel extends Controller {

    public function install() {
        $this->load->model('setting/event');

        // The trigger is a plain string. A typo here gives no error:
        // the handler is simply never called.
        $this->model_setting_event->addEvent('upper_model',
            'admin/model/catalog/product/addProduct/before',
            'extension/module/upper_model/beforeAddProduct'
        );
        $this->model_setting_event->addEvent('upper_model',
            'admin/model/catalog/product/editProduct/before',
            'extension/module/upper_model/beforeEditProduct'
        );
    }

    public function uninstall() {
        $this->load->model('setting/event');
        $this->model_setting_event->deleteEventByCode('upper_model');
    }

    // addProduct($data): $args[0] is $data.
    // Both parameters must be references, otherwise changes are lost silently.
    public function beforeAddProduct(&$route, &$args) {
        if (isset($args[0]['model'])) {
            $args[0]['model'] = strtoupper($args[0]['model']);
        }
        // Return nothing: in OpenCart 3 a non-null value returned from a
        // "before" handler replaces the result, the original addProduct()
        // is not called and the remaining handlers are skipped.
    }

    // editProduct($product_id, $data): here $args[0] is $product_id
    // and $args[1] is $data.
    public function beforeEditProduct(&$route, &$args) {
        if (isset($args[1]['model'])) {
            $args[1]['model'] = strtoupper($args[1]['model']);
        }
    }
}

Things you have to watch here:

  • The handler does not know what it receives. $args is just the method's arguments in order. To learn that $args[0] is the product data in one case and the product ID in the other, you have to open admin/model/catalog/product.php and read the signatures. Neither the IDE nor PHP will help.
  • One change needs two handlers with different indexes.
  • A model is intercepted from a controller. In OpenCart 3 an event handler is always a controller method, even when it changes a model method. If the handler needs data from the database, you either write SQL queries in the controller, although OpenCart keeps SQL in models, or create one more model just for the handler and load it from the controller. Either way the model logic is split between a controller and a model, and the code looks clumsy.
  • Mistakes are silent. A typo in the route, a missing & or a stray return produce no warning and no error log entry. The module just stops working, or breaks other modules' handlers.
  • The route-to-handler link lives in the oc_event table. It has to be registered on install and removed on uninstall.

With Ka Extensions: the minimum set of files

Ka Extensions does not require a module installer or a language file. Three files are enough (vendor mycompany, module upper_model):

Files
admin/controller/extension/mycompany/upper_model/kamod.ini              manifest
admin/controller/extension/mycompany/upper_model/active.kamod           "module is enabled" marker, may be empty
admin/model/extension/mycompany/upper_model/model/catalog/product.php   override

The model override, admin/model/extension/mycompany/upper_model/model/catalog/product.php. Since it is a model, SQL queries through $this->db can go right here when they are needed:

PHP
<?php
namespace extension\mycompany\upper_model;

class ModelCatalogProduct extends \ModelCatalogProduct {

    public function addProduct($data) {
        $data = $this->normalizeModel($data);
        return parent::addProduct($data);
    }

    public function editProduct($product_id, $data) {
        $data = $this->normalizeModel($data);
        parent::editProduct($product_id, $data);
    }

    protected function normalizeModel($data) {
        if (isset($data['model'])) {
            $data['model'] = strtoupper($data['model']);
        }
        return $data;
    }
}

The kamod.ini manifest. One line is enough; other fields such as install_after are optional:

INI
name = "Upper case product model"

The active.kamod file tells kamod that the module is enabled. Only its presence matters, so it can be empty. After uploading the files, refresh the kamod cache: Extensions → Modifications → Refresh, or on the Ka Extensions page. During development the KAMOD_DEBUG constant rebuilds the cache on every request.

Such a module is not visible anywhere in the admin interface, but it works. To switch it off, delete active.kamod and refresh the cache again.

What you get:

  • The parameters have the same names as in the core: $data, $product_id. You can see what is changed and what is passed on.
  • The result is a plain return. If you need the new product ID, it is right there: $product_id = parent::addProduct($data);.
  • Shared logic goes into a protected method, like normalizeModel(), instead of being duplicated across two handlers.
  • A model is changed by a model. Database work stays where OpenCart keeps it.
  • Mistakes are easier to spot. If the method signature does not match the parent, PHP reports it, and the IDE shows the parent's methods and parameters.
  • No database records. The module is enabled by the active.kamod file.
To be fair, you can make mistakes with Ka too. If you forget to call parent::addProduct(), the product is not saved and the chain of other modules on that method is cut. The effect is as bad as a stray return in an event, but it is visible when you read the code.

Optional: installer and language file

If you want the module to appear on the Ka Extensions page, where it can be installed and uninstalled, add an installer and a language file. Then you do not upload active.kamod yourself: the Ka Extensions page creates it when the module is installed and deletes it on uninstall.

Files
admin/controller/extension/mycompany/upper_model.php                    installer
admin/controller/extension/mycompany/upper_model/kamod.ini              manifest
admin/language/en-gb/extension/mycompany/upper_model.php                language
admin/model/extension/mycompany/upper_model/model/catalog/product.php   override

The installer, admin/controller/extension/mycompany/upper_model.php. It only declares versions; nothing needs to be registered:

PHP
<?php
namespace extension\mycompany;

class ControllerUpperModel extends \extension\ka_extensions\ControllerSettings {

    protected $ext_code = 'upper_model';

    protected $extension_version = '1.0.0.0';
    protected $min_store_version = '3.0.0.0';
    protected $max_store_version = '3.0.9.9';
    protected $min_ka_extensions_version = '4.1.1.11';
    protected $max_ka_extensions_version = '4.1.1.99';
}

class_alias(__NAMESPACE__ . '\ControllerUpperModel', 'ControllerExtensionMycompanyUpperModel');

Several modules on one method

Both mechanisms support this.

  • With events, handlers on the same route run in sort_order.
  • With Ka Extensions, each module becomes a link in the inheritance chain. The first module extends the core class, the second extends the first, and so on, each calling parent::. The order is set with install_before and install_after in kamod.ini.

Measurements

How we measured

  • Environment: OpenCart 3.0.5.1, PHP 8.3.36, OPcache on, JIT off, MariaDB 11.8, the PHP built-in server with one worker. The catalog is tiny, so pages are fast: about 23–25 ms.
  • Plain OpenCart: every scenario has Ka Extensions and the stock OpenCart events installed, 39 storefront events in total. A stock product or home page performs about 310 event checks (trigger): before and after every model call, controller, template and language load.
  • One "module" does the same work both ways. It adds a key to the result of getProduct(), adds a variable to the product/product template, and hooks a test model and controller. The event version uses 4 events; the Ka version uses 4 override classes.
  • Scenarios: plain OpenCart; events with 10 modules (40 events); Ka with 10 modules; 50 registered events that never match. We also measured one module of each kind, but a single module makes no noticeable difference either way, so it is not shown.
  • Volume: each page was requested 2,000 times per scenario, in 4 rounds with the scenarios taking turns. Single calls were measured 20,000 times per run, 12 runs.
  • Typical time. For each scenario we sorted all the times and took the middle one: half of the requests were faster and half were slower. Unlike an average, this typical time is not thrown off by a few random slow requests.
  • Outliers: two stalled requests (480 s and 49 s, both with events and 10 modules) were excluded. That is 2 requests out of 24,000, and they do not change the typical times.
  • Noise: the typical time of separate rounds varied by about ±2 ms, around ±8%. Differences under 1.5 ms (about 6%) are treated as noise.

Percentages are calculated as (scenario − plain OpenCart) / plain OpenCart × 100%.

Comparison with 10 modules

Page times are in milliseconds (ms). Single calls are in microseconds (µs): 1 µs is a thousandth of a millisecond.

What is compared Plain OpenCart OpenCart events, 10 modules Ka Extensions, 10 modules
Product page, typical time 0% (24.5 ms) +16.7% (28.6 ms) + 1% (24.8 ms)
Home page, typical time 0% (22.6 ms) +18.3% (26.7 ms) + 1% (22.9 ms)
Product pages per second 0% (40.4 ms) +15% (44.3 ms) + 1% (41.8 ms)
  • Every registered event costs time on every check, even if it never matches. Event::trigger() loops over all events and runs preg_quote and preg_match for each. That is ≈ 0.3 µs per event per check, with about 310 checks per page. As a result, 50 events that do nothing at all slowed the product page by +24% (30.4 ms) and the home page by +26% (28.6 ms), more than 10 working modules did. The cost of events grows with every installed module, even on pages that module does not use.

Forecast for 50 modules

Method. Linear extrapolation. The dispatcher's design justifies it: Event::trigger() checks every registered event on every call, so the cost grows in proportion to the number of events. We calculated it two ways:

  1. Per-module slope: (10 modules − plain OpenCart) / 10 = +0.41 ms per module, or +1.7% of the product page. For 50 modules: 50 × 0.41 ≈ +20.4 ms.
  2. Per-event cost: (50 idle events − plain OpenCart) / 50 = +0.117 ms per event. 50 modules with 4 events each make 200 events: 200 × 0.117 ≈ +23.5 ms.

Assumptions: 4 events per module, as in the test; about 310 checks per page, as in the test; handlers do almost nothing, so only the mechanism's own cost is measured, not the module's useful work. That useful work is the same in both approaches and is left out of the comparison. A real store with 50 modules usually performs more checks per page, so this estimate is probably on the conservative side.

Number of modules Events, product page Events, home page Ka Extensions
10 (measured) +17% (+4.1 ms) +18% (+4.1 ms) ≈ 0% (noise)
50 (forecast) +83…96% (+20…24 ms) +91…105% (+21…24 ms) ≈ 0%, estimate < 1%

On the test store, 50 event-based modules would nearly double the page time from the event dispatcher alone.

The Ka estimate: one link in the chain costs ≈ 0.025 µs. Even if all 50 modules overrode the same method and it were called 100 times per page, that would be 50 × 100 × 0.025 µs ≈ 0.13 ms, about 0.5% of the page. In practice modules override different methods, so the cost is even lower.

What about a real store?

Real pages are heavier, 150–400 ms. There, the same absolute overhead looks smaller:

Usual page time of the store Events, 10 modules Events, 50 modules (forecast) Ka Extensions
150 ms +2.7% +14…16% ≈ 0%
250 ms +1.6% +8…9% ≈ 0%
400 ms +1.0% +5…6% ≈ 0%
We do not claim that events are the main reason a store is slow. Most of the time usually goes to SQL, templates and the network. But the cost of events grows with every module, while Ka stays at zero. The more modules a store has, the more the difference shows.

Strengths of each mechanism

OpenCart events

Strengths:

  • They are the official OpenCart mechanism. They exist in every store and need no third-party library.
  • No generated code or class cache: the handler is called directly.
  • A single event can be disabled in the admin, under Extensions → Events.
  • They work well for small, targeted hooks, especially on template output.

Things to keep in mind:

  • Handlers are controllers, even for model events, and receive their parameters as an unnamed array.
  • Every registered event adds a little time to every event check on every page.
  • Events have to be registered in the database on install and removed on uninstall.
Our view on this: in practice you almost never need to disable a single event in the admin. A module is one piece, and switching off part of it is more likely to break it than to help. With Ka, a module is enabled or disabled as a whole.

Ka Extensions

Strengths:

  • Ordinary PHP inheritance: a child class, a method with the same named parameters, parent:: and return. The IDE and PHP itself check the code.
  • A model is changed by a model and a controller by a controller, so SQL stays in models.
  • Zero overhead per module, no matter how many modules are installed.
  • A minimal module is three files with no database records: kamod.ini, active.kamod and the override class.
  • A module is enabled or disabled as a whole, on the Ka Extensions page or with the active.kamod file.
  • If something goes wrong, the administrator has Safe Mode, which opens the admin without the kamod cache.

Things to keep in mind:

  • The Ka Extensions library has to be installed.
  • Kamod generates override classes and keeps them in a cache. The cache has to be refreshed when module files change. During development the KAMOD_DEBUG constant rebuilds it on every request.
  • Each override should call parent::, otherwise the chain of other modules on that method is cut.

Conclusion

  • Convenience. With Ka you write ordinary PHP: a child class, a method with the same parameters, parent:: and return. Overriding a function parameter is one line with a clear name. With events you have to unpack the $args array every time, remember what each index holds, keep the return rules in mind, and handle model events in a controller.
  • Speed. With 10 modules, events cost +17…18% of page time, Ka ≈ 0%. For 50 modules the forecast for events is +83…105% on the test store and +5…16% on a real one, while Ka stays near zero.
  • Order and chains exist in both mechanisms. Neither has an advantage here.
Both mechanisms work, and events are still a fine choice for small changes. But if a store has many modules, or you want code that is clear and easy to check, inheritance with Ka Extensions saves both server time and developer time.

See also: Ka Extensions for OpenCart 3 documentation · Ka Extensions for OpenCart 4 documentation