| name | opencart-3-workflow |
| description | Краткая практическая инструкция: как работать с OpenCart 3, его архитектурой и OCMOD (модификации). |
OpenCart 3 — Быстрый навигатор для разработчика
Цель: дать понятную, повторяемую процедуру для разработки, отладки и развёртывания изменений в OpenCart 3 и управления модификациями через OCMOD.
- Структура и роли
catalog/ — фронтенд (клиентская часть).admin/ — панель администратора (контроллеры, модели, виды).system/ — ядро: библиотека, storage, modification, config.- MVC-L: контроллеры (
controller/*), модели (model/*), шаблоны/виды (view/* — Twig/OC template).
- Языковые файлы в
language/*.
- Где правим исходники
- Разработку модулей вести в
dev-modules/<имя_модуля>/upload (структура в upload должна повторять catalog/ и admin/).
- НЕЛЬЗЯ править файлы напрямую в
opencart (root OpenCart) — можно только просматривать для понимания.
- OCMOD (модификации)
- OCMOD — XML-патчи, которые модифицируют поведение без правки ядра.
- Места хранения применённых модификаций:
system/storage/modification.
- Для создания/обновления OCMOD: положите XML в модуль или загрузите через админ-панель, затем очистите кеш модификаций и примените.
- Для создания/обновления OCMOD: положите XML в модуль или загрузите через админ-панель, затем очистите кеш модификаций и примените.
- OCMOD-файлы также можно размещать в
system/ (например system/<имя_модуля>.ocmod.xml) или в dev-modules/<имя_модуля>/upload/system/ — при установке/развёртывании модуля такие файлы будут доступны для установки. Всё равно после добавления/обновления нужно выполнить Refresh модификаций.
- Локальная проверка и развёртывание модуля
- В папке модуля выполните
ocm install (если в проекте есть утилита ocm) — это применит/скопирует файлы из dev-modules/<имя_модуля>/upload в рабочий OpenCart.
- После установки обновите кеш модификаций и шаблонов в админке (Extensions → Modifications → Refresh, and Dashboard → Gear → Refresh Cache).
- Проверяйте результат в
system/storage/modification и логах (system/storage/logs/).
- Отладка и полезные приёмы
- Для поиска точек входа используйте структуру маршрутов: контроллер → модель → view.
- При ошибках OCMOD смотрите логи модификаций и временные файлы в
system/storage/modification.
5.a) system/library — назначение и неймспейсы
system/library содержит общие библиотеки и классы ядра OpenCart. По умолчанию OpenCart не следует PSR-4/именованным пространствам для своих core-классов — он использует собственный загрузчик (Loader/Registry).- Рекомендации:
- Не изменяйте напрямую файлы в корневом
system/library — это приводит к коллизиям и потерям при обновлении.
- Если нужен общий класс/библиотека для модуля, размещайте её внутри модуля:
dev-modules/<имя_модуля>/upload/system/library/<vendor>/<package>/... и загружайте через стандартный load->library() или регистрируйте автозагрузчик.
- При использовании неймспейсов предпочитайте Composer/автозагрузчик: добавьте зависимости в
vendor/ и регистрируйте автозагрузку, либо используйте уникальный префикс/неймспейс, чтобы избежать конфликтов с ядром и другими модулями.
- Избегайте переопределения core-классов в
system/library; вместо этого создавайте отдельные namespaced-классы и инжектируйте их через registry/DI.
- Практические правила команды
- Все исходные правки модулей — только в
dev-modules/<имя_модуля>/upload.
- Не дублируйте изменения в
opencart — модуль или OCMOD должен обеспечивать изменение.
- Для PR включайте только файлы из
dev-modules/<имя_модуля>/upload и OCMOD (если требуется), указывайте в описании: "Изменения через модуль <имя_модуля>".
- Контроль качества перед PR
- Запустите
git status и убедитесь, что изменения лежат только в dev-modules/<имя_модуля>.
- Протестируйте сценарии: установка модуля, применение OCMOD, ключевые пользовательские пути (checkout, product view и т.д.).
- Частые ошибки и как их избегать
- Прямая правка ядра — приводит к утрате изменений при обновлении. Решение: OCMOD или модуль.
- Несовпадение путей в
upload и OpenCart — файл не применяется. Решение: повторяйте точную структуру (admin/controller/..., catalog/view/...).
Примеры команд
- Установить/обновить модуль (в папке модуля):
ocm install
- Очистить кеш и применить модификации — через админку (Modifications → Refresh) или вручную удалить кеш в
system/storage/cache и system/storage/modification где применимо.
Подсказки для Copilot / агентов:
- Предлагай изменения и новые файлы только внутри
dev-modules/<имя_модуля>/upload.
- Если нужен пример OCMOD — генерируй валидный XML с описанием цели и точками вставки, и указывай, что файл нужно положить в модуль и установить через админку или
ocm install.
Если нужно — расширим этот навигатор чеклистом для PR или шаблоном OCMOD XML.
