OpenCart 4 под микроскопом: архитектура, Twig, REST API, Event система — разбор кода ядра

с учётом практики команды с 17-летним опытом разработки на OpenCart — OpenCart 4 — это не просто «новая версия». Это полностью переписанная архитектура: Twig вместо PHP-шаблонов, Composer-автозагрузка, Event-система вместо OCMOD, Service Container и настоящий REST API с JWT-аутентификацией. Разбираю ключевые изменения в коде ядра — для разработчиков, которые хотят мигрировать или писать модули под OC4.

Из практики: в одном проекте клиенту нужно было вывести дополнительный блок на карточке товара. Зная структуру шаблона, доработка заняла 20 минут. В этой статье — подробная карта файлов OpenCart, чтобы вы тоже ориентировались быстро.

OpenCart 4 (на момент статьи — версия 4.1.0.3) — это архитектурный переворот для платформы. Ядро было переписано с нуля с использованием современных PHP-практик. В этой статье разбираю ключевые изменения на уровне кода — для разработчиков, которые хотят понять, что изменилось и как писать модули под OC4.

1. Composer и PSR-4 автозагрузка

В OC3 загрузка классов происходила через кастомный автозагрузчик в system/engine/loader.php и system/library/ и была нестандартной. В OC4 всё построено на Composer с PSR-4 автозагрузкой.

Пример структуры кастомного модуля в OC4:

upload/├── extension/my_extension/│   ├── admin/│   │   ├── controller/│   │   ├── language/│   │   ├── model/│   │   └── view/twig/│   └── catalog/│       ├── controller/│       ├── language/│       ├── model/│       └── view/twig/├── system/│   └── config/│       └── my_extension.php└── install.xml

namespace — только для библиотек. Контроллеры, модели и языковые файлы используют префиксные пути, как и в OC3, но с поддержкой PSR-4 для библиотек.

2. Twig — теперь по умолчанию

OC3 получил Twig позже (версия 3.0.x), но поддерживал и старые PHP-шаблоны (.tpl). OC4 использует только Twig (.twig). Никакого смешивания — только Twig.

Пример .twig-шаблона:

{# OC4 Twig template example #}{{ header }}{{ column_left }}{{ content_top }}
{{ heading_title }}
{% for product in products %}  
        
{{ product.name }}
    
{{ product.price }}
  
{% endfor %}{{ footer }}

Плюсы: экранирование по умолчанию (безопасность), наследование шаблонов, макросы, фильтры. Минусы: нужно переписывать все .tpl-шаблоны, некоторые старые модули несовместимы.

3. Event система — замена OCMOD

OCMOD в OC3 работает через парсинг XML-файлов и модификацию PHP-кода на лету. Это удобно, но медленно и ненадёжно. OC4 вводит Event-систему, вдохновлённую WordPress hooks.

Регистрация события:

<!-- В install.xml модуля --><event>  <code>my_extension_view_product_before</code>  <trigger>catalog/view/product/product/before</trigger>  <action>extension/my_extension/catalog/event/view_product</action></event>

Обработчик события:

class ControllerExtensionMyExtensionCatalogEventViewProduct extends Controller {    public function index(string &$route, array &$data): void {        // Модифицируем данные до рендера шаблона        $data['extra_block'] = $this->load->controller('extension/my_extension/module/extra');    }}

Event-система работает на уровне PHP, без парсинга XML. Это быстрее и безопаснее. Старые OCMOD-моды для OC3 не работают в OC4 — их нужно переписывать.

4. REST API с JWT

В OC3 REST API — это базовый набор эндпоинтов с аутентификацией по API-ключу (Basic Auth). В OC4 — полноценный REST API с JWT-токенами, Bearer-аутентификацией, CORS и rate limiting.

Пример работы с API OC4:

// Получение токенаPOST /index.php?route=api/account/login{  "username": "API-пользователь",  "key": "api_key_123"}→ { "token": "eyJhbGciOiJIUzI1NiIs..." }// Запрос с JWTGET /index.php?route=api/product&limit=10Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Новые эндпоинты OC4: api/product, api/category, api/cart, api/checkout, api/order, api/customer. Все — с JSON request/response.

5. Service Container

OC4 использует Service Container (через library/Container.php) для внедрения зависимостей. Реестр (Registry) из OC3 остался, но теперь он работает в паре с контейнером.

Пример:

// OC4 Service Container$container->set('log', function($container) {    return new Log($container->get('config')->get('error_filename'));});$logger = $container->get('log');$logger->write('debug message');

6. Миграция с OC3 на OC4: что нужно знать

Если вы решите мигрировать с OC3 на OC4, вот список необходимых действий:

• Шаблоны: все .tpl → .twig. Полная переработка темы.
• Модули: все OCMOD-моды → Event-система. Полная переработка расширений.
• БД: скрипт миграции обновляет схему. Тестируйте на копии БД.
• API: если использовали API OC3 — переход на JWT. Старый API несовместим.
• Библиотеки: если писали свои — возможно, потребуется адаптация под PSR-4.

Наш вердикт: OC4 — это технологически правильный шаг. Но для продакшена, если вам нужна стабильность и модули — пока берите OC3. Если вы готовы писать модули сами и вам нужны новые возможности API — OC4.

Часто задаваемые вопросы

Стоит ли мигрировать с OC3 на OC4 сейчас?
Если ваш магазин работает и приносит деньги — не торопитесь. OC3 стабилен и будет получать обновления безопасности. OC4 — для новых проектов.

Можно ли использовать OCMOD-модули в OC4?
Нет. OCMOD не поддерживается в OC4. Нужно переписывать модули под Event-систему.

Рекомендации из практики

Как лучше: Начните изучение OpenCart 4 с Event system — это главное нововведение. События позволяют расширять функционал без OCMOD и не затрагивают файлы ядра. Просто зарегистрируйте обработчик на триггер controller/*/before — и ваш код выполнится до вызова контроллера.

Как не делать: Не пытайтесь перенести OCMOD-модули с OC3 на OC4 без адаптации. OpenCart 4 использует Twig, а не TPL. REST API стал строже. Прямой перенос без переписывания под новые стандарты не сработает.

Кейс из практики: Клиент решил обновиться с OC3 до OC4 и просто скопировал все модули. Половина не работала из-за TPL → Twig и изменённого API. Пришлось переписывать модули заново под архитектуру OC4. Вывод: обновление OC3→OC4 требует аудита модулей.

Нужна помощь —

По практике, закажите доработку OpenCart: проведём аудит и подготовим модули к OC4.

FAQ

Что такое Event-система в OpenCart 4?

Это механизм хуков, который позволяет подписаться на события (before/after) без модификации файлов ядра. Чистый способ расширения.

Работает ли OCMOD в OpenCart 4?

Нет, в OC4 OCMOD заменён Event-системой. Для обратной совместимости есть модуль-обёртка, но лучше переходить на Events.

Стоит ли переходить с OC3 на OC4?

Если есть совместимые модули — да. Если нет — лучше остаться на OC3 и ждать развития экосистемы OC4.

Нужна помощь с OpenCart?

Проектируете новый проект на OC4? Мы разрабатываем магазины на OpenCart 4 с использованием современной архитектуры. Разработка на OpenCart 4.

Читайте также:

• API OpenCart

Из практики. При интеграции OpenCart с внешними сервисами через API стандартная настройка часто подводит: лимит запросов не учитывается, токены не обновляются. В одном проекте магазин интегрировали с CRM через REST API — через неделю API перестал отвечать, так как не был настроен лимит запросов. Мы добавили очередь запросов и тротлинг — интеграция работает стабильно уже полгода.

Как не надо. Не подключайтесь к внешним API без обработки ошибок. Всегда добавляйте: retry-логику при временных ошибках, тротлинг запросов (чтобы не превысить лимиты), логирование ошибок с уведомлением администратору. И никогда не храните API-ключи в публичной части кода — выносите их в конфиг.