Модули OpenCart: установка без поломок

Модули — главная сила и главная слабость OpenCart. Под любую задачу есть готовое решение, но каждый модуль вмешивается в код магазина, и десяток модулей от разных авторов легко начинают мешать друг другу. Разберём, как устроены модули, как ставить их без риска и что делать, когда после установки всё сломалось.

Как устроены модули в OpenCart

Модуль OpenCart обычно состоит из трёх частей:

1. Свои файлы — контроллеры, модели, шаблоны, языковые файлы. Они кладутся в папки admin/ и catalog/ и ничего не перезаписывают.
2. Модификатор — описание изменений в чужих файлах. Например, «в файле catalog/controller/checkout/cart.php после строки X вставь строку Y». В OpenCart 2.x–3.x это OCMOD (XML-файл install.xml), в старых сборках — vQmod.
3. Таблицы и настройки в базе, которые создаются при установке.

OCMOD не меняет оригинальные файлы. Он создаёт их изменённые копии в папке storage/modification (в OpenCart 3 — system/storage/modification), и магазин использует копии. Поэтому любой модификатор можно отключить одной кнопкой, а оригинальные файлы остаются чистыми.

В OpenCart 4 механизм поменялся: модули оформляются как расширения со своей папкой в extension/, а OCMOD поддерживается в упрощённом виде. Модули от 3-й версии в 4-й не работают.

Где брать модули

• Официальный маркетплейс opencart.com — много модулей, но качество разное, и не все обновляются.
• Русскоязычные площадки под OpenCart и ocStore — удобны для локальных задач: доставка СДЭК и Европочта, оплата ЕРИП, SEO для ocStore.
• Сайты разработчиков модулей — у крупных авторов есть поддержка и обновления.

Не скачивайте «бесплатные» версии платных модулей с варез-сайтов. В них регулярно встречаются бэкдоры: код, который отправляет злоумышленнику доступы или создаёт администратора. Лечить потом магазин дороже, чем купить модуль.

Перед покупкой проверьте:

• для какой версии модуль: 2.3, 3.0.x, 4.0.x и отдельно для ocStore;
• когда было последнее обновление;
• поддерживает ли модуль вашу версию PHP;
• есть ли отзывы от владельцев магазинов с похожим набором модулей.

Правильная установка: по шагам

1. Резервная копия. Файлы и база. Минимум — база и папки admin, catalog, system.

2. Проверка совместимости. Версия OpenCart видна внизу админки. Версия PHP — в панели хостинга.

3. Загрузка. Расширения — Установка расширений — «Загрузить», файл с расширением .ocmod.zip. Если архив называется иначе, внутри обычно папка upload и install.xml — их нужно запаковать в ocmod.zip или залить вручную по FTP.

Если установщик пишет ошибку FTP — в OpenCart 3 зайдите в Система — Настройки — вкладка «FTP» или используйте модуль, который отключает FTP-установку. Частое решение — просто залить папку upload по FTP в корень магазина, а install.xml загрузить через установщик.

4. Обновление модификаторов. Расширения — Модификаторы — кнопка «Обновить» (синяя, с круговой стрелкой). Без этого изменения OCMOD не применятся. Половина обращений «поставил модуль, а он не работает» решается этой кнопкой.

5. Очистка кэша шаблонов. В OpenCart 3: на главной странице админки — кнопка с шестерёнкой справа вверху — обновить кэш шаблонов (Twig) и кэш SASS.

6. Права доступа. Система — Пользователи — Группы пользователей — Administrator — отметить новый модуль в «Разрешено просматривать» и «Разрешено изменять». Иначе при открытии модуля будет «У вас нет прав».

7. Установка и включение. Расширения — Расширения — выбрать тип (модули, доставка, оплата) — «Установить» (зелёный плюс) — «Редактировать» — включить.

Почему ломается магазин после установки

Конфликт модификаторов

Два модуля пытаются изменить одну и ту же строку в одном файле. Первый применяется, второй не находит строку и пропускается — или, хуже, вставляет код в неожиданное место. Признаки: белый экран, ошибка 500, перестала работать корзина или фильтр.

Где смотреть: Расширения — Модификаторы — вкладка «Лог». Там видно, какой модификатор не нашёл строку поиска:

MOD: Modification Default
FILE: catalog/controller/checkout/cart.php
CODE: $data['totals'] = array();
NOT FOUND - OPERATIONS ABORTED!

Решение — поправить install.xml модуля под ваш код или поменять порядок модификаторов.

Несовместимость с PHP 8

Модули, написанные под PHP 5.6–7.x, падают на PHP 8 с ошибками вроде count(): Argument must be of type Countable или Undefined array key. Временно помогает возврат версии PHP. Правильно — обновить модуль или исправить код.

Модуль не для вашей версии

Модуль для OpenCart 2.3 на 3.0 частично работает, а частично — нет. Модуль для 3.0 на 4.0 не работает вообще.

Сломанный кэш

После отключения модуля магазин продолжает его использовать. Удалите содержимое storage/modification и storage/cache, затем нажмите «Обновить» в модификаторах.

Если магазин лёг полностью

1. Не трогайте базу.
2. Переименуйте папку storage/modification (или удалите её содержимое). Магазин заработает на оригинальных файлах без модификаторов.
3. Зайдите в админку, отключите последний установленный модификатор, нажмите «Обновить».
4. Если админка тоже не открывается — смотрите лог ошибок в storage/logs/error.log. Подробнее — в статье «Ошибка 500 на сайте».

Как не превратить магазин в свалку модулей

• Ставьте модуль сначала на копию магазина.
• Удаляйте модули, которыми не пользуетесь, вместе с их модификаторами.
• Ведите список: какой модуль, откуда, для чего, какая версия.
• Не правьте файлы модулей напрямую — пишите свой модификатор поверх, чтобы правка пережила обновление.
• Выбирайте модули от авторов, которые обновляют их хотя бы раз в год.

Когда нужен свой модуль

Если готовый модуль закрывает задачу на 60% и требует костылей, часто дешевле написать небольшой свой. Например, вывод остатков по складам, особая логика скидок или выгрузка заказов в CRM. Свой модуль делает только то, что нужно, и не тянет за собой лишний код.

Про выбор версии магазина — в статье «OpenCart 3, 4 или ocStore». Если модули уже конфликтуют или нужен свой — это задача для доработки OpenCart.

Как написать свой простой модификатор

Если нужно чуть поправить поведение модуля или ядра, не трогая файлы, достаточно небольшого OCMOD. Пример: добавить в карточку товара блок с текстом о доставке после цены.

<?xml version="1.0" encoding="utf-8"?>
<modification>
  <name>Delivery note in product</name>
  <code>delivery_note</code>
  <version>1.0</version>
  <author>anba.by</author>
  <file path="catalog/view/theme/*/template/product/product.twig">
    <operation>
      <search><![CDATA[{% if price %}]]></search>
      <add position="before"><![CDATA[<div class="delivery-note">Доставка по Беларуси 1–3 дня</div>]]></add>
    </operation>
  </file>
</modification>

Сохраните файл как install.xml, запакуйте в архив с именем delivery_note.ocmod.zip и загрузите через установщик расширений. Затем «Обновить» в модификаторах и очистка кэша Twig. Если строка поиска не найдена, это будет видно в логе модификаторов.

Как проверить, какой модуль замедляет магазин

После десятка модулей магазин часто начинает тормозить. Порядок проверки:

1. Замерьте время ответа главной, категории и карточки товара.
2. Отключите модули по одному (в Расширения — Модули) и повторяйте замер.
3. Отдельно проверьте модификаторы: отключение модификатора и «Обновить».
4. Включите медленный лог MySQL на копии и посмотрите, какие запросы выполняются дольше секунды.

Частые виновники — модули фильтров без кэша, «просмотренные товары», счётчики остатков и модули, которые на каждой странице обращаются к внешним сервисам.

Типичный конфликт модулей

На ocStore 3 ставят модуль SEO-фильтра, и после установки перестаёт работать кнопка «Купить» в категориях. В логе модификаторов видно, что два модуля — фильтр и быстрый заказ — меняют один и тот же фрагмент шаблона категории. Фильтр применяется вторым и не находит строку поиска, потому что первый модуль её уже изменил.

Решение: поменять строку поиска в install.xml фильтра на ту, что остаётся после работы модуля быстрого заказа, обновить модификаторы и очистить кэш. Оба модуля продолжают обновляться штатно, а правка живёт в отдельном модификаторе.

Чек-лист установки модуля

1. Модуль для вашей версии OpenCart или ocStore и версии PHP.
2. Резервная копия файлов и базы.
3. Установка на копию магазина.
4. Загрузка через установщик, «Обновить» в модификаторах.
5. Очистка кэша Twig.
6. Права группе администраторов.
7. Установка и включение модуля.
8. Проверка главной, категории, карточки, корзины и оформления заказа.
9. Проверка лога модификаторов и журнала ошибок.
10. Перенос на рабочий магазин.

Частые вопросы