Классическая история: разработчик поправил пару строк прямо в catalog/controller/product/product.php, магазин заработал как надо, все забыли. Через полгода обновление движка или перенос на другой хостинг, файлы перезаписаны, правка исчезла. Что именно было изменено, никто уже не помнит, потому что никаких следов не осталось. А бывает хуже: правок набралось десятки, разбросаны по всему каталогу, и отличить авторский код от системного можно разве что через diff с чистой сборкой.
Именно от этого спасает OCMOD. Это штатная система модификаций OpenCart, встроенная начиная с версии 2.0 (идейный наследник vQmod, только без отдельной установки). Суть простая: вы описываете правку в XML-файле по принципу «найди такую строку, вставь такой код», а движок применяет её сам, не трогая оригиналов.
Что происходит под капотом
OCMOD никогда не редактирует системные файлы. Вместо этого он берёт оригинал, вносит изменения в его копию и складывает её в кеш модификаций: system/storage/modification/. Когда сайт работает, автозагрузчик сначала ищет файл именно там, и только если модифицированной копии нет, берёт оригинал.
Сами XML-инструкции хранятся в базе, в таблице oc_modification. Кнопка Обновить (Refresh) в разделе Расширения → Модификаторы перечитывает все активные модификаторы из базы и перестраивает кеш заново. Пока вы её не нажали, ваши правки не применятся.
Минимальный модификатор
Рабочий пример: добавляем свой код на главную страницу.
<?xml version="1.0" encoding="utf-8"?>
<modification>
<name>Мій перший модифікатор</name>
<code>my_first_mod</code>
<version>1.0</version>
<author>Ви</author>
<link>https://example.com</link>
<file path="catalog/controller/common/home.php">
<operation>
<search><![CDATA[$data['column_left'] = $this->load->controller('common/column_left');]]></search>
<add position="after"><![CDATA[
$data['my_variable'] = 'Привіт з OCMOD';
]]></add>
</operation>
</file>
</modification>
Шапка (name, code, version, author, link) обязательна: без неё установщик файл не примет. code должен быть уникальным, иначе новый модификатор перезапишет в базе старый с тем же кодом. Иногда это используют намеренно для обновлений, но чаще это сюрприз, когда два разных модуля от одного автора вдруг «съедают» друг друга.
Весь код в search и add заворачивайте в <![CDATA[ ]]>. PHP-код полон символов <, >, &, и без CDATA вы получите невалидный XML.
search и add: где прячутся нюансы
Тег <search> ищет вхождение в пределах одной строки. Это самое важное, что нужно знать об OCMOD, и именно на этом спотыкается большинство новичков. Вставили в search блок из трёх строк кода, модификатор молча не применился. Для многострочных сценариев формально есть атрибут offset и регулярные выражения, но к обоим далее будут оговорки.
Атрибуты search:
trim="true"— обрезает пробелы по краям перед сравнением (по умолчанию и так true, но полезно знать);index— если искомая строка встречается в файле несколько раз, ограничивает правку конкретными вхождениями. Нумерация с нуля:index="0"— первое вхождение,index="2"— третье. Можно перечислить несколько:index="0,2". Это классическая ловушка для тех, кто переходит с vQmod, потому что там отсчёт с единицы. Без index правка ляжет на все совпадения, что иногда именно то, что нужно, а иногда катастрофа;
Атрибуты add:
position—before,afterилиreplace. По умолчанию replace, поэтому если забыли указать position, ваш код не добавится к найденной строке, а заменит её. Проверяйте это первым делом, когда «почему-то пропал» кусок оригинального кода;offset="2"— смещение в строках. Например,position="after" offset="2"вставит код не сразу после найденной строки, а через две. Аposition="replace" offset="2"заменит найденную строку плюс две следующие.
Только с offset есть беда, из-за которой я бы его вообще не трогал. Он считает строки наугад, не глядя, что в них написано. Если другой модификатор вставил свой код рядом с вашим якорем, или тема либо обновление движка сдвинули файл на строку-две, offset молча заменит или заденет совсем не то, что вы имели в виду. Журнал ошибок при этом чистый: search нашёл свою строку, операция формально успешна. Такие баги потом ловят очень долго.
Надёжная тактика: искать не одну строку с offset, а разбить правку на несколько операций, где каждый search цепляется за уникальную содержательную строку. Тогда модификатор либо применится точно куда надо, либо не применится вовсе и честно напишет об этом в журнал. Второе поведение намного лучше, чем «применился не туда». Offset оставляйте на крайний случай, когда рядом просто нет стабильной строки для якоря, и обязательно с минимальным значением.
С регулярками отдельная история. Когда regex="true", атрибуты position, trim и offset не работают: всё управляется самим выражением, как в preg_replace. Доступен разве что limit для ограничения количества замен. И учтите давний недостаток: комбинация regex с position before/after вела себя некорректно и удаляла найденный фрагмент, поэтому с регулярками безопасно полагаться только на логику полной замены. Честно говоря, в девяти случаях из десяти регулярки в OCMOD не нужны. Обычный поиск с index покрывает почти всё и читается намного легче.
Отдельно о путях. В path работают маски, и это спасает при работе с темами:
<file path="catalog/view/theme/*/template/product/product.twig">
Звёздочка вместо названия темы означает «применить ко всем темам». Без неё модификатор, написанный под default, просто не найдёт файлов вашей темы Promo или любой другой.
OpenCart 2.x против 3.x: что изменилось
Разница существенная, и именно на ней ломаются инструкции из интернета.
В OpenCart 2.x через Расширения → Установка можно было загрузить как архив *.ocmod.zip, так и голый файл *.ocmod.xml. Архив мог содержать install.sql с запросами к базе и install.php, которые выполнялись при установке.
В OpenCart 3.x установщик принимает только *.ocmod.zip. Внутри архива модификатор должен называться строго install.xml, а файлы модуля лежать в папке upload/ (структура папки повторяет структуру сайта). И принципиально: install.php и install.sql в 3.x штатно больше не выполняются. Если модуль для тройки требует изменений в базе, он делает их через метод install() своего контроллера, а не через SQL-файл в архиве. Старые мануалы для 2.x здесь откровенно вредят: человек упаковывает install.sql, загружает, а таблицы в базе не появляются, и он ищет проблему не там.
Если админка по какой-то причине недоступна или установщик капризничает с правами, никто не запрещает закинуть содержимое upload/ по FTP вручную, а сам install.xml добавить через сторонний редактор модификаторов. Но это уже план Б.
Типичные грабли
Забыли нажать «Обновить». Лидер с большим отрывом. Модификатор установлен, активен, а на сайте ничего не изменилось. Расширения → Модификаторы → Обновить, и чудо случается.
search не находит строку. Вторая по частоте причина «не работающего» модуля. Вы ищете строку из чистого OpenCart, а в файле она уже другая: тема переопределила шаблон или другой модификатор раньше заменил этот фрагмент через position="replace". OCMOD применяет модификаторы последовательно, и каждый следующий работает с результатом предыдущих.
Правка оригинала не дала эффекта. Зеркальная ситуация: вы правите системный файл руками, а сайт игнорирует изменения. Вспомните о кеше: сайт читает копию из system/storage/modification/, а не ваш отредактированный оригинал. После ручных правок файлов, на которые распространяются модификаторы, кеш нужно перестроить той же кнопкой «Обновить».
И отдельная мелочь, которая стоит часов: OCMOD не валидирует атрибуты строго. Напишете possition вместо position, и XML загрузится без единой жалобы, просто молча сработает дефолтный replace. Прежде чем искать сложные причины, перечитайте атрибуты по буквам.
Если магазин лёг после модификатора
Бывает: кривой модификатор заменил не то, и на сайте белая страница. Без паники, оригиналы целы. Порядок действий такой: зайти в админку (она обычно живёт, потому что ломают чаще каталог), отключить подозрительный модификатор, нажать «Обновить». Если легла и админка, удалите содержимое system/storage/modification/ по FTP — сайт сразу начнёт работать на чистых оригиналах, без всякой модификации. Дальше спокойно заходите в админку, ищете виновника и перестраиваете кеш.
Кстати, для диагностики в разделе модификаторов есть журнал: туда попадают сообщения о том, какие операции не применились и почему. Прежде чем винить разработчика модуля, загляните туда, часто ответ лежит на поверхности: search не нашёл строку, потому что её уже переписал соседний модификатор.
Кому OCMOD не лучший выбор
Для расширения логики контроллеров в OpenCart 2.2+ есть система событий (events): подписка на before/after вызовы без всякого поиска строк. События устойчивее к обновлениям и не конфликтуют между собой так, как текстовые замены. Правило из практики такое: для PHP-логики сначала смотрите, не решается ли задача событием, а OCMOD оставляйте для шаблонов, языковых файлов и мест, куда события не дотягиваются. И ещё одно ограничение по определению: OCMOD работает с файлами движка, поэтому правки в самих файлах кеша или в сторонних скриптах вне структуры OpenCart он не сделает. Но события (events) — это отдельная статья.
Чек-лист: пишем и ставим модификатор
- Проверьте шапку XML:
name,code,version,author,linkна месте,codeуникален. - Весь код в
searchиaddзавернут в CDATA. - В
searchтолько одна строка кода. Многострочные правки разбивайте на отдельные операции с уникальными якорями,offset— только как крайний случай. positionуказан явно, даже если это replace.- Для шаблонов тем в пути стоит маска
theme/*/. - Для OC 3.x: архив
*.ocmod.zip, внутриinstall.xmlплюс папкаupload/. На install.sql не рассчитывайте. - После установки — Расширения → Модификаторы → Обновить. Всегда.
- Изменения не применились — сначала журнал модификаторов, затем проверка, существует ли искомая строка в файле из кеша.
- Сайт лёг — отключить модификатор и обновить кеш, в крайнем случае очистить
system/storage/modification/по FTP. - Перед редактированием системных файлов руками вспомните, что сайт читает копии из кеша модификаций.