OCMOD в OpenCart: правки коду без зміни системних файлів

Класична історія: розробник поправив пару рядків прямо в 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) - це окрема стаття.

Чек-лист: пишемо й ставимо модифікатор

1. Перевірте шапку XML: name, code, version, author, link на місці, code унікальний.
2. Весь код у search та add загорнутий у CDATA.
3. У search лише один рядок коду. Багаторядкові правки розбивайте на окремі операції з унікальними якорями, offset — лише як крайній випадок.
4. position вказаний явно, навіть якщо це replace.
5. Для шаблонів тем у шляху стоїть маска theme/*/.
6. Для OC 3.x: архів *.ocmod.zip, усередині install.xml плюс папка upload/. На install.sql не розраховуйте.
7. Після установки — Розширення → Модифікатори → Оновити. Завжди.
8. Зміни не застосувалися — спершу журнал модифікаторів, потім перевірка, чи існує шуканий рядок у файлі з кешу.
9. Сайт ліг — вимкнути модифікатор і оновити кеш, у крайньому разі очистити system/storage/modification/ по FTP.
10. Перед редагуванням системних файлів руками згадайте, що сайт читає копії з кешу модифікацій.