Події

Вступ#

ocStore 3 (як і OpenCart 3.0) використовує систему подій, яка дає змогу розширювати й змінювати функціональність ядра, не редагуючи його код. Система подій дозволяє «підключатися» до певних точок у життєвому циклі застосунку, виконувати власний код і змінювати дані чи поведінку. У цьому посібнику пояснюється, як працювати з подіями в ocStore: реєструвати, викликати й обробляти їх, з практичними прикладами.

Що таке система подій#

Система подій в ocStore побудована за моделлю «видавець — передплатник». Події викликаються в певних точках застосунку, а розробник може зареєструвати слухачів (обробників), які виконуватимуть власний код, коли ці події настають. Завдяки цьому ocStore легко розширювати: додавати власну логіку, змінювати дані чи інтегрувати сторонні сервіси.

Основні складники#

Подія: іменована точка виклику в коді (наприклад, catalog/controller/product/category/before).
Слухач: метод, що виконується, коли подія настає.
Реєстр подій: механізм, який зіставляє події з їхніми слухачами (таблиця oc_event у базі даних і об'єкт $this->event).
Виклик (trigger): запуск події, під час якого виконуються зареєстровані слухачі.

Іменування подій#

Подія ідентифікується рядком-тригером у форматі застосунок/тип/маршрут/етап.

Застосунок: catalog (вітрина) або admin (адмінпанель).
Тип: що саме перехоплюється — controller, model, view, language або config.
Маршрут: шлях до файлу та, за потреби, метод, розділені / (наприклад, checkout/cart/add — метод add() контролера checkout/cart).
Етап: коли настає подія — before (до) або after (після).

Приклад: catalog/controller/product/product/before викликається перед виконанням контролера сторінки товару на вітрині. Для методу index() метод у маршруті не вказується (правильно: product/product, неправильно: product/product/index). На відміну від OpenCart 4, метод відділяється звичайною косою рискою /, а не крапкою.

У тригерах можна використовувати символи підстановки * (будь-яка послідовність) і ? (один символ), наприклад catalog/view/*/before.

Поширені події#

Ось кілька подій, які часто використовують:

catalog/view/product/product/before: перед виведенням шаблону сторінки товару.
catalog/view/common/content_top/after: після виведення блоку content_top.
catalog/controller/checkout/cart/add/after: після додавання товару до кошика.
catalog/model/checkout/order/editOrder/before: перед редагуванням замовлення.
catalog/model/checkout/order/addOrderHistory/after: після зміни статусу замовлення.
catalog/controller/checkout/confirm/after: після підтвердження замовлення.

Аргументи слухача#

Слухач отримує аргументи за посиланням і може їх змінювати:

Тип події	`before`	`after`
`controller`	`&$route, &$args`	`&$route, &$args, &$output`
`model`	`&$route, &$args`	`&$route, &$args, &$output`
`view`	`&$route, &$data, &$code`	`&$route, &$data, &$output`
`language`	`&$route, &$key`	`&$route, &$key, &$output`

Якщо слухач повертає значення, відмінне від null, виконання інших слухачів цієї події припиняється, а повернене значення використовується як результат (для before — замість виклику оригінального методу).

Як зареєструвати слухача події#

Слухачі реєструються в реєстрі подій — таблиці oc_event. Зазвичай це робиться в коді вашого модуля чи доповнення під час його встановлення.

Кроки реєстрації слухача#

Створіть метод-слухач: напишіть метод, який оброблятиме подію.
Зареєструйте подію: зв'яжіть тригер події зі слухачем через модель setting/event.
Забезпечте доступність: переконайтеся, що файл слухача лежить там, де його шукає завантажувач.

Приклад: реєстрація слухача події#

Припустімо, потрібно виконати власний код перед додаванням товару до кошика на вітрині (catalog/controller/checkout/cart/add/before).

Крок 1. Створіть слухача

Створіть контролер для свого доповнення. Наприклад, розмістіть такий код у файлі catalog/controller/extension/module/test_module.php:

<?php
class ControllerExtensionModuleTestModule extends Controller {
  public function onCartAddBefore(&$route, &$args) {
    // Process your customizations here
    $this->log->write('onCartAddBefore() has been successfully triggered!');
  }
}

Крок 2. Зареєструйте подію

Події зазвичай реєструють у методі install() контролера доповнення в адмінпанелі за допомогою моделі setting/event.

Додайте такий код у контролер модуля admin/controller/extension/module/test_module.php:

<?php
class ControllerExtensionModuleTestModule extends Controller {
  public function install() {
    // Load the event model
    $this->load->model('setting/event');

    // Register the event: code, trigger, action, status, sort_order
    $this->model_setting_event->addEvent(
      'test_module_cart_add_before',                     // Event code (unique identifier)
      'catalog/controller/checkout/cart/add/before',     // Event trigger
      'extension/module/test_module/onCartAddBefore',    // Listener method
      1,                                                 // Status
      1                                                  // Sort order
    );
  }

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

Крок 3. Перевірте подію

Завантажте доповнення через Доповнення → Установка доповнень (або скопіюйте файли на сервер).
Встановіть модуль у Доповнення → Доповнення (тип «Модулі»), щоб виконався метод install().
Переконайтеся, що подія з'явилася й увімкнена в Доповнення → Події.
Додайте товар до кошика на вітрині.
Відкрийте Система → Обслуговування → Журнал помилок і переконайтеся, що там з'явилося ваше повідомлення.

На відміну від OpenCart 4, в ocStore 3 подія виконується, якщо вона ввімкнена в Доповнення → Події, незалежно від статусу самого модуля. Якщо обробник має працювати лише для ввімкненого модуля, перевіряйте статус у коді слухача, наприклад if ($this->config->get('module_test_module_status')) { … }.

Виклик власних подій#

Ви також можете викликати власні події. Це корисно для модулів і доповнень, які мають сповіщати інші частини системи.

Під час реєстрації з тригера прибирається перший сегмент (catalog/ чи admin/), тому подію, зареєстровану з тригером catalog/extension/module/test_module/custom_action/after, на вітрині треба викликати як extension/module/test_module/custom_action/after.

Викличте подію методом trigger() реєстру подій. Наприклад, у catalog/controller/extension/module/test_module.php:

// Data to pass to event
$data = array('message' => 'Custom action executed');

// Trigger a custom event (arguments are passed as an array)
$this->event->trigger('extension/module/test_module/custom_action/after', array(&$data));

Найкращі практики#

Зрозумілі назви: дотримуйтеся формату застосунок/тип/маршрут/етап і давайте подіям унікальні коди з префіксом свого доповнення.
Без змін ядра: використовуйте систему подій або модифікатори (OCMOD), щоб ваш код не ламався під час оновлень.
Обережно з даними: завжди перевіряйте й очищуйте дані, що передаються слухачам.
Продуктивність: уникайте важких обчислень у слухачах, щоб не сповільнювати магазин.
Ретельне тестування: перевіряйте слухачів у різних сценаріях.
Прибирання під час видалення: завжди видаляйте події в методі uninstall(), щоб у базі не лишалося «осиротілих» записів.

Налагодження подій#

Журнал помилок: увімкніть запис помилок (Система → Налаштування, вкладка Сервер, параметр Записувати помилки) і перевіряйте Система → Обслуговування → Журнал помилок.
Реєстрація події: переконайтеся, що подію зареєстровано й увімкнено в Доповнення → Події.
Покрокова перевірка: тестуйте слухачів по одному, щоб локалізувати проблему.

Сторінку перекладено й адаптовано для ocStore з офіційної документації OpenCart. Ліцензія — GNU GPL v3.

Оновлено: 23.10.2026

Документація