Модификаторы OCMOD: Полное руководство по кастомизации OpenCart (OcStore) 2/3/4

Пишу для себя шпаргалку по созданию модификаторов ocmod для OpenCart (OcStore). Возможно будет полезна и вам. Коротко и по делу. Начнем.

Что такое OCMOD и зачем он нужен?

OCMOD (OpenCart Modifier) — система, позволяющая дорабатывать, расширять или заменять функциональность и визуальное оформление OpenCart без правки исходных файлов. Этот подход, сохраняет целостность оригинальной системы, одновременно предоставляя неограниченные возможности для кастомизации.
Модификаторы появились в версии 1.5.x в виде vQmod, а с версии 2x функционал был доработан и преобразован в OCMOD.

Модификатор OCMOD представляет собой XML-файл, содержащий четкие инструкции для системы: какие файлы, в каких местах и каким образом должны быть модифицированы. При активации модификатора OpenCart создает продублированные версии целевых файлов в специальной директории кэша, применяя все указанные изменения именно к этим копиям, не изменяя оригинальные файлы.

Ключевые преимущества:

• Сохранение оригинальных файлов в неизменном виде
• Простота управления модификаторами
• Быстрый откат изменений

Структура и требования к модификаторам

Формат архивов и файлов

Архив модификатора должен строго соответствовать требованиям: «имя_модификатора».ocmod.zip. Система автоматически игнорирует файлы, не соответствующие этому шаблону.

Особенности для разных версий OpenCart:

• OpenCart 2.x — модификаторы можно загружать через установщик в формате «название».ocmod.xml
• OpenCart 3.x — модификатор включается в состав модуля. Основной файл модификации должен называться install.xml
• Альтернативный метод (НЕ рекомендуется) — ручная загрузка через FTP в папку system с именем файла в формате «название».ocmod.xml

Директории и логи системы

Кэш модификаций располагается по пути system/storage/modification/, тут сохраняется зеркальная структура файловой системы с внесенными изменениями.

Система логирования включает два основных файла в system/storage/logs/:

• ocmod.log — детальная хронология выполнения модификаций
• error.log — регистрация ошибок и проблем при обработке

Обновление кэша модификаций

Для применения изменений необходимо выполнить обновление кэша через административную панель: Модификаторы → Обновить. В случаях, когда изменения не вступают в силу, необходимо очистить дополнительные кэширующие модули, если они используются на сайте.

Синтаксис и структура OCMOD

Базовый шаблон модификатора:

<?xml version="1.0" encoding="utf-8"?>
<modification>
  <name>Название модификатора</name>
  <version>1.0</version>
  <author>Алексей [KWORK]</author>
  <link>https://kwork.ru/user/kam1kadze/</link>
  <code>shortdescription_link</code>
 
  <file path="catalog/controller/product/category.php">
    <operation>
      <search>
        <![CDATA[
          $result['name'],
        ]]>
      </search>
      <add position="after">
        <![CDATA[
          'model'    => $result['model'],
          'sku'      => $result['sku'],
        ]]>
      </add>
    </operation>
  </file>
</modification>

Детальный разбор тегов OCMOD

Тег <file> — определение целевых файлов

Указывает пути к модифицируемым файлам с поддержкой различных форматов указания:

Выбор файла:

<file path="catalog/controller/product/category.php">

Множественный выбор через «|»:

<file path="catalog/controller/product/category.php|catalog/controller/product/search.php">

Сокращение кода с использованием фигурных скобок:

<file path="catalog/controller/product/{category,search}.php">

Использование маски «*»:

<file path="catalog/view/theme/*/template/product/*.twig">

Тег <operation> — блок модификаций

Секция модификации, может быть несколько секций при модификации файла. Поддерживает атрибут error (не обязательно) с вариантами поведения:

<operation error="skip">

• skip — пропуск текущей операции при ошибке
• log — пропуск всего файла (значение по умолчанию)
• abort — полная остановка обработки модификатора

Тег <search> — точное определение целевого кода

Ключевые особенности:

• Используется только один раз внутри секции operation
• Поддержка только однострочного поиска всей строки целиком или её части
• Обязательное использование <![CDATA[ … ]]>
• Автоматическое игнорирование пробелов (если не указано иное)

Атрибуты для точного позиционирования:

• index — порядковый номер вхождения (0 — первое)
• trim — управление обработкой пробелов (true/false)
• regex — использование регулярных выражений

Практический пример:

<search index="1" trim="true"><![CDATA[
  $data['products'][] = array(
]]></search>
<search regex="true"><![CDATA[
  ~(require|include)(_once)?\(([^)]+)~
]]></search>

Разберем компоненты этого выражения:

• ~ — разделитель регулярного выражения
• (require|include) — группа, ищущая «require» ИЛИ «include»
• (_once)? — необязательная группа «_once» (знак ? означает 0 или 1 вхождение)
• \( — экранированная открывающая скобка
• ([^)]+) — захватывающая группа, содержащая всё, кроме закрывающих скобок

Тег <add> — внесение изменений

Параметры позиционирования:

• replace — замена найденного кода
• before — вставка перед целевым кодом
• after — вставка после целевого кода
• offset — смещение на указанное количество строк

Пример комплексного использования:

<add position="after" offset="2" trim="true"><![CDATA[
  <li class="custom-feature">{{ custom_content }}</li>
]]></add>

• Всегда создавайте резервные копии перед внедрением модификаций
• Тестируйте изменения на тестовом сайте
• Документируйте вносимые изменения
• Объединяйте связанные модификации в одном файле
• Минимизируйте количество операций в одном файле
• Используйте точные поисковые запросы для уменьшения времени обработки
• Проверяйте XML-файлы на корректность синтаксиса
• Используйте уникальные коды модификаций для предотвращения конфликтов
• Регулярно обновляйте кэш модификаций после изменений

Спасибо за внимание (=
Не забудьте добавить сайт в закладки (Ctrl+D)