Обновление OpenCart без потери доработок: чек-лист

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

Сначала определите, что именно обновляется

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

Запишите исходное состояние магазина:

• точную версию OpenCart и PHP;
• версию MySQL или MariaDB;
• веб-сервер и способ запуска PHP;
• список установленных расширений и их версии;
• изменённые файлы темы, контроллеров, моделей и языковых пакетов;
• активные OCMOD-модификации и события;
• подключённые платёжные, доставочные и аналитические сервисы.

Версию PHP и требования целевой сборки сверяйте с официальной документацией и страницей конкретного релиза. Нельзя считать, что магазин на OpenCart 3.x автоматически готов к последней версии PHP: совместимость зависит от сборки, расширений и стороннего кода.

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

Модификация^* — изменение поведения магазина без прямой правки исходного файла, например через OCMOD или механизм событий. На практике такая модификация может конфликтовать с новой версией файла, даже если сам модуль формально установлен.

Выберите стратегию обновления

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

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

Что проверить до копирования файлов

1. Зафиксируйте рабочую точку

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

Не храните единственный архив на том же сервере. Если сервер выйдет из строя или резервная копия окажется повреждённой, такой файл не поможет.

2. Найдите ручные изменения

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

Особенно внимательно проверьте:

• файлы темы и шаблоны карточки товара, корзины и оформления заказа;
• контроллеры каталога и checkout;
• модели, связанные с ценами, остатками, налогами и заказами;
• языковые файлы и настройки маршрутов;
• правила веб-сервера и задания cron.

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

3. Проверьте расширения

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

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

4. Подготовьте тестовое окружение

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

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

Как проводить обновление на копии

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

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

Что проверять перед продакшеном

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

• Каталог: категории, фильтры, поиск, цены, скидки, варианты товара и остатки.
• Покупатель: регистрация, вход, восстановление пароля, личный кабинет и адреса.
• Checkout: гостевой заказ, несколько способов доставки, промокод, налоги, округление и повторный заказ.
• Оплата: успешный платёж, отказ, возврат со страницы платёжного сервиса и смена статуса заказа.
• Администрирование: редактирование товара, загрузка изображения, просмотр заказа, экспорт и права пользователей.
• Интеграции: обмен с CRM или складом, вебхуки, письма, cron-задачи и аналитические события.
• Производительность: время ответа главной страницы и checkout, ошибки PHP, нагрузка на базу и место на диске.

Составьте таблицу «сценарий — ожидаемый результат — фактический результат — статус». Такой список полезнее общей формулировки «всё проверили»: после переноса на продакшен его можно пройти ещё раз.

Что ломается чаще всего

Тема перезаписывает доработки

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

OCMOD применился не к тому коду

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

Расширение установилось, но конфликтует с другим

Так проявляются два модуля, меняющие один контроллер, checkout или способ расчёта цены. Отключайте кандидатов по одному на тестовой копии и фиксируйте результат. На продакшене не решайте конфликт методом случайного удаления файлов.

После обновления появляются 500 и белая страница

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

Перенос в продакшен и откат

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

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

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

Что делать дальше

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