Переход с OpenCart 2 на 3 и 4: что ломается

После перехода с OpenCart 2 на OpenCart 3 магазин может открыть главную страницу, но потерять оформление, способы оплаты и часть заказов в админке. При переходе на OpenCart 4 к этому добавляются изменения в структуре расширений и требованиях к окружению. Ниже — разбор несовместимостей для OpenCart 2.3.x, 3.0.x и 4.0.x: что проверять до миграции, какие ошибки появляются первыми и как не превращать рабочий магазин в набор исключений.

Главная ошибка — считать миграцию обновлением файлов

OpenCart хранит не только каталог товаров и заказы. В базе и файловой системе живут настройки темы, маршруты контроллеров, установленные модификаторы, языковые файлы, права пользователей и параметры платёжных модулей. Поэтому схема «сделать резервную копию, заменить файлы и открыть сайт» опасна: база может загрузиться, а код расширения — обращаться к классам, шаблонам или путям старой версии.

Безопаснее разделить задачу на два независимых результата:

• перенос данных — товары, категории, клиенты, заказы, настройки;
• перенос кода — тема, модификаторы, модули оплаты, доставки, аналитики и интеграции.

Первый результат проверяется по данным. Второй — по пользовательским сценариям. Успешный импорт базы ещё не означает, что покупатель сможет оформить заказ.

Миграция OpenCart ломается не в момент копирования базы, а в первом сценарии, который никто не прогнал: поиск, корзина, оплата, возврат или письмо клиенту.

Что меняется между OpenCart 2, 3 и 4

Ниже не матрица совместимости всех дополнений, а карта рисков. Конкретное расширение нужно проверять по заявленной версии, коду и инструкции разработчика.

OCMOD — механизм модификации файлов OpenCart без прямего редактирования оригиналов. Система создаёт изменённую копию файла; поэтому после установки или изменения модификатора важно обновить кеш модификаций и проверить, какой код реально исполняется.

Что ломается первым

Тема и Twig-шаблоны

На OpenCart 2 многие темы и дополнения меняют шаблоны напрямую или рассчитывают на конкретный HTML-контекст. В OpenCart 3 стандартная тема использует Twig, а старый файл может не находиться по ожидаемому пути. Результат бывает разным: от белого блока товара до ошибки синтаксиса Twig.

Проверяйте не только внешний вид. Откройте карточку товара с опциями, измените количество, добавьте товар в корзину, авторизуйтесь и пройдите оформление. Отдельно проверьте мобильное меню и всплывающие окна: они часто зависят от JavaScript-обработчиков темы, а не только от шаблона.

OCMOD и порядок применения изменений

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

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

Модули оплаты и доставки

Платёжный модуль может выглядеть установленным, но не передавать заказ в платёжную систему. После перехода проверяйте создание заказа, сумму, валюту, статус, возврат покупателя и серверное уведомление о результате оплаты. Тестовый платёж в интерфейсе модуля не заменяет полный заказ из корзины.

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

Маршруты, ссылки и SEO-URL

Старые ссылки могут вести на страницу 404, а включённые SEO-URL — работать только для части каталога. Риск повышается, если в магазине есть собственные контроллеры, ЧПУ-модуль или правила веб-сервера, которые переносились вручную.

Составьте список URL из аналитики и карты сайта до миграции. После переноса проверьте коды ответа, канонические ссылки, пагинацию, фильтры и редиректы со старых адресов. Не исправляйте всё массовым перенаправлением на главную: поисковик и пользователь должны попасть на соответствующую страницу.

Права, кеш и админка

Расширение может быть физически загружено, но скрыто от пользователя из-за отсутствующих прав группы администратора. Другая частая причина ложного диагноза — старый кеш темы или модификаций: вы меняете файл, а сайт продолжает отдавать предыдущую версию.

После установки дополнения проверьте четыре вещи: оно видно в списке, его настройки сохраняются, у администратора есть права на маршрут, а результат виден в пользовательской части сайта. Если хотя бы один пункт не выполняется, переходить к следующему расширению рано.

Как организовать миграцию без простоя

1. Зафиксируйте исходное состояние. Сохраните резервную копию базы и файлов, список расширений, версию PHP, настройки веб-сервера и перечень нестандартных правок. Проверка: резервная копия разворачивается на отдельном стенде, а не просто лежит архивом на том же сервере.
2. Соберите стенд. Разверните копию магазина на отдельном домене или закрытом окружении. Не подключайте к нему боевые ключи оплаты, доставки и рассылок. Проверка: тестовый заказ не уходит реальному платёжному провайдеру и не отправляет письмо настоящему клиенту.
3. Определите целевую версию. Сверьте требования целевого OpenCart, PHP, базы данных, темы и всех критичных расширений. Если поставщик модуля поддерживает только OpenCart 3, перенос на 4 означает замену или доработку модуля, а не простое копирование.
4. Перенесите данные отдельно от расширений. После импорта проверьте количество категорий, товаров, клиентов и заказов, а также цены, остатки, опции и адреса. Проверка: несколько записей из каждой группы совпадают с боевым магазином по ключевым полям.
5. Установите совместимые тему и расширения. Не переносите каталог старых модулей целиком. Сначала ставьте тему, затем поиск, корзину, оплату, доставку, интеграции и аналитику. Проверка: после каждого компонента открываются главная, каталог и карточка товара.
6. Прогоните пользовательские сценарии. Выполните покупку без регистрации и с регистрацией, примените промокод, выберите доставку, оплатите тестовый заказ, проверьте письмо и изменение статуса. Проверка: заказ виден в админке, сумма в нём совпадает с корзиной, а обратный статус обрабатывается.
7. Подготовьте переключение. Сократите окно заморозки заказов, повторите перенос изменившихся данных и заранее составьте план отката. Проверка: вы знаете, какой архив восстановить, как вернуть DNS или конфигурацию веб-сервера и кто принимает решение об откате.

Как понять, что проблема именно в несовместимости

Сначала смотрите журналы OpenCart и PHP, затем воспроизводите ошибку в чистом сценарии. Если ошибка исчезает после отключения одного расширения, это сильный признак конфликта, но не доказательство: модуль мог только первым вызвать повреждённые данные или старую настройку.

• Белая страница или HTTP 500. Ищите фатальную ошибку PHP, несовместимый вызов или отсутствие файла. Не лечите симптом увеличением лимита памяти, пока не прочитали журнал.
• Страница открывается без оформления. Проверьте тему, пути к CSS и JavaScript, кеш темы и ошибки браузера. После миграции домена также проверьте абсолютные URL в настройках и базе.
• Модификатор установлен, но ничего не меняет. Обновите кеш модификаций, проверьте журнал применения и сравните целевой путь с файлами именно вашей версии OpenCart.
• В админке нет пункта расширения. Проверьте права группы пользователя, способ установки и маршрут контроллера. Успешная загрузка архива не гарантирует корректной регистрации модуля.
• Оплата создала заказ, но статус не изменился. Проверьте адрес обратного вызова, журнал веб-сервера, подпись запроса и соответствие режима тестовой или боевой оплаты. Секреты и ключи не переносите в открытые тикеты или резервные копии без защиты.

Где подход ломается

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

Особенно рискованны расширения, которые меняют оформление заказа, цены, остатки, налоги или статусы заказов. Их нельзя заменять похожим модулем без проверки данных и бизнес-правил: внешне одинаковая кнопка может по-разному создавать заказ и передавать сумму в платёжную систему.

Отдельная тема — обновление базы данных и сохранение старых URL. Здесь нельзя рассчитывать на универсальный сценарий: способ миграции зависит от версии магазина, объёма данных, кастомных таблиц и используемого расширения. Перенос SEO-данных и редиректов планируйте как самостоятельную задачу.

Что делать после переключения

Первые дни после запуска смотрите не только на доступность сайта. Отслеживайте ошибки PHP, 4xx и 5xx, долю брошенных корзин, неуспешные платежи, расхождение остатков и время ответа оформления заказа. Сравнивайте показатели с периодом до миграции, а не с ощущением администратора.

После стабилизации удалите неиспользуемые расширения, уберите временные тестовые доступы, обновите резервное копирование и зафиксируйте версии OpenCart, PHP, темы и модулей. Следующим практическим шагом будет отдельный аудит оформления заказа и платёжных уведомлений: именно там несовместимость чаще всего превращается в потерянную выручку.