OpenCart ошибки: как найти причину и восстановить работу магазина

Ошибка в OpenCart может выглядеть совершенно по-разному:

• белая страница;
• 500 Internal Server Error;
• предупреждение или Fatal error PHP;
• магазин открывается, а админка нет;
• ошибка появляется только при оформлении заказа;
• перестал работать установленный модуль;
• после обновления пропала часть функций;
• изменения внесены, но на сайте их не видно;
• OpenCart сообщает, что у пользователя нет прав на действие.

У этих симптомов нет одного универсального исправления.

Поэтому первое правило диагностики — не менять всё подряд, а сначала определить точное место сбоя.

Сначала зафиксируйте, что именно сломалось

Перед изменениями ответьте на несколько вопросов:

• магазин вообще открывается?
• административная часть открывается?
• ошибка появляется на всех страницах или только на одной?
• проблема есть у всех пользователей или только у одного администратора?
• работает ли корзина?
• открывается ли оформление заказа?
• проблема появилась после установки расширения?
• после обновления OpenCart?
• после изменения PHP?
• после переноса сайта?
• после изменения темы?

Очень важно вспомнить последнее изменение перед появлением ошибки.

Например:

> установили модуль → появилась ошибка

намного полезнее для диагностики, чем просто:

> OpenCart сломался.

Сохраните полный текст ошибки

Если OpenCart или PHP показывает сообщение об ошибке, сохраните его целиком.

Не только последнюю строку.

Полезны:

• тип ошибки;
• имя файла;
• номер строки;
• путь;
• название класса или функции;
• SQL-сообщение;
• HTTP-код;
• время появления ошибки.

Например, сообщения:

Class ... not found

и:

Access denied for user ...

могут визуально одинаково «сломать страницу», но причины у них совершенно разные.

Первое указывает на код или загрузку файлов, второе — на подключение к базе данных.

Проверьте журнал ошибок OpenCart

OpenCart имеет собственный механизм журналирования.

В текущем коде OpenCart каталог журналов определяется через DIR_LOGS, связанный с каталогом storage. Само приложение записывает сообщения в файл журнала через встроенный класс Log.

Точный физический путь зависит от установки.

Он может выглядеть примерно так:

.../storage/logs/

В документации OpenCart для расширений также рекомендуется при ошибках проверять журналы в system/storage/logs/, но в реальной установке storage может быть перемещён.

Поэтому не ищите error.log только по одному адресу из случайной инструкции.

Сначала определите фактический DIR_STORAGE / DIR_LOGS вашей установки.

Storage может находиться не внутри папки сайта

В современных установках OpenCart каталог storage рекомендуется размещать за пределами публичной директории сайта. Это делается в том числе для безопасности.

Поэтому ситуация:

> в system/storage/logs ничего нет

ещё не означает, что OpenCart не ведёт журнал.

Путь мог быть изменён при установке.

Посмотрите config.php и admin/config.php и определите фактическое значение DIR_STORAGE.

После этого уже ищите каталог:

logs

внутри реального storage.

Не показывайте подробные PHP-ошибки посетителям постоянно

Во время диагностики разработчику иногда нужно увидеть точное PHP-сообщение.

Но постоянно выводить подробные ошибки на рабочем интернет-магазине не стоит.

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

На рабочем магазине правильнее:

1. записывать ошибку в журнал;
2. диагностировать её администратору;
3. не показывать посетителю внутренние пути, классы и технические детали сервера.

Если OpenCart показывает 500 Internal Server Error

500 Internal Server Error — это не название конкретной ошибки OpenCart.

Это означает, что сервер не смог нормально выполнить запрос.

Причина может находиться в:

• PHP;
• конфигурации веб-сервера;
• расширении OpenCart;
• изменённых файлах;
• неверной конфигурации;
• правах доступа;
• несовместимости после обновления.

В такой ситуации одного OpenCart-журнала может быть недостаточно.

Проверьте также журнал PHP и веб-сервера.

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

Если ошибка появилась после установки модуля

Расширения — одна из первых вещей, которые стоит проверить, если проблема началась сразу после их установки или обновления.

OpenCart использует расширения для модулей, оплаты, доставки, тем и другой функциональности. В OpenCart 4 расширения могут также использовать Events и OCMOD.

Если проблема появилась сразу после нового расширения:

1. зафиксируйте ошибку;
2. проверьте журнал;
3. определите название установленного расширения;
4. проверьте, какие файлы и модификации оно добавляет;
5. временно отключите именно подозрительное расширение, если это можно сделать безопасно;
6. повторите исходное действие.

Не отключайте десять модулей одновременно.

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

Проверьте модификации OCMOD

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

В актуальной документации разработчика после установки OCMOD указаны отдельные действия:

обновить modifications и очистить cache.

Поэтому после:

• установки расширения;
• удаления расширения;
• изменения OCMOD;
• обновления файлов модуля

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

Но очистка кеша тоже не является универсальным лечением.

Если PHP выдаёт конкретный Fatal error, сначала разберите именно его.

Если изменения внесли, а сайт показывает старую версию

Не каждая такая проблема является ошибкой PHP.

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

Проверяйте по уровням:

1. кеш OpenCart;
2. кеш модификаций, если применимо;
3. кеш темы или расширения;
4. кеш браузера;
5. внешний серверный кеш, если он используется.

Не удаляйте произвольные каталоги на сервере, не выяснив сначала, какой кеш они содержат.

Если проблема появилась после обновления OpenCart

Обновление затрагивает не только файлы ядра.

Могут иметь значение:

• версия самого OpenCart;
• расширения;
• тема;
• изменённый код;
• база данных;
• миграции;
• кеш.

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

Если ошибка появилась именно после обновления, не начинайте со случайного изменения PHP-настроек.

Сначала сравните:

что работало до обновления и что изменилось вместе с ним.

Проверьте config.php

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

В частности, там определяются:

• расположение системных каталогов;
• storage;
• параметры базы данных;
• имя базы;
• пользователь;
• порт;
• префикс таблиц.

Это видно и в официальном installer-коде OpenCart, который формирует config.php.

После:

• переноса сайта;
• смены домена;
• переезда на другой сервер;
• изменения структуры каталогов;
• восстановления из резервной копии

особенно важно проверить, что конфигурация соответствует фактическому новому окружению.

Ошибка подключения к базе данных

Если сообщение указывает на MySQL или MariaDB, проверьте параметры подключения.

В конфигурации OpenCart используются данные вроде:

DB_HOSTNAME
DB_USERNAME
DB_PASSWORD
DB_DATABASE
DB_PORT
DB_PREFIX

Набор этих параметров формируется самой установкой OpenCart.

Проверьте:

• существует ли база;
• правильный ли пользователь;
• правильный ли пароль;
• имеет ли пользователь доступ к этой базе;
• правильный ли hostname;
• правильный ли порт;
• не изменился ли префикс таблиц.

Не создавайте новую базу и не переустанавливайте OpenCart только потому, что старые реквизиты подключения оказались неправильными.

Если ошибка только в административной панели

Если магазин работает, а администратор видит сообщение о недостаточных правах, причина может быть не в PHP.

OpenCart использует группы пользователей с отдельными правами:

• Access;
• Modify.

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

Поэтому сообщение вроде:

You do not have permission to modify...

сначала требует проверки группы администратора и разрешений.

Не нужно менять файлы ядра для обхода нормальной системы прав.

Если проблема только в одном разделе магазина

Это хороший диагностический признак.

Например:

• главная работает, товар падает;
• каталог работает, checkout падает;
• магазин работает, конкретный модуль нет;
• всё работает, кроме одной страницы админки.

Чем уже область сбоя, тем меньше компонентов нужно проверять.

Смотрите:

1. какой controller/route выполняется;
2. какое расширение относится к функции;
3. что написано в журнале в момент запроса;
4. какие изменения недавно делались именно в этом разделе.

Не начинайте с полной переустановки OpenCart.

Если ошибка связана с оформлением заказа

Checkout зависит сразу от нескольких компонентов:

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

Поэтому сообщение «не работает оформление заказа» ещё слишком широкое.

Нужно определить точный шаг, на котором ломается процесс.

Например:

• не появляется способ доставки;
• не появляется способ оплаты;
• заказ не создаётся;
• после подтверждения происходит ошибка;
• платёж прошёл, а статус заказа не изменился.

Только после этого имеет смысл разбирать конкретную интеграцию.

Если проблема появилась после изменения PHP

Проверяйте не только сам OpenCart.

Расширение или старая тема могут использовать код, который работал в одной версии PHP и перестал работать после смены окружения.

Если проблема появилась сразу после изменения PHP:

1. зафиксируйте установленную версию;
2. проверьте полный Fatal error;
3. определите файл или расширение из сообщения;
4. проверьте совместимость конкретной версии OpenCart и расширений;
5. не маскируйте ошибку простым отключением её отображения.

Отсутствие сообщения на экране не означает, что код стал исправным.

Проверьте необходимые PHP-компоненты

OpenCart зависит от PHP и ряда расширений.

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

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

• файлы те же;
• база та же;
• OpenCart тот же;
• но новая система PHP настроена иначе.

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

Не путайте ошибку OpenCart с ошибкой расширения

Если traceback или журнал указывает на файл стороннего модуля, это важная информация.

Например, проблема внутри:

extension/...

не обязательно является ошибкой самого ядра OpenCart.

Сначала локализуйте компонент.

Это особенно важно после установки:

• платёжного модуля;
• доставки;
• обмена;
• темы;
• SEO-расширения;
• импорта;
• интеграции с внешним сервисом.

Иначе можно начать менять ядро, хотя сбой находится полностью внутри одного расширения.

Не редактируйте ядро наугад

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

Так можно временно скрыть симптом и одновременно создать новую проблему.

Лучше определить:

• это файл ядра?
• расширения?
• темы?
• модифицированная копия?
• несовместимость версий?
• результат OCMOD?

OpenCart рекомендует использовать расширения, Events и OCMOD вместо бесконтрольного изменения core-кода.

Перед серьёзным исправлением сделайте резервную копию

Особенно если предстоит:

• обновлять OpenCart;
• менять расширения;
• править базу;
• заменять файлы;
• менять тему;
• исправлять конфигурацию.

Официальная инструкция обновления отдельно рекомендует иметь полную резервную копию файлов и базы и тестировать серьёзное обновление на staging.

Резервная копия нужна до изменения, а не после того, как магазин окончательно перестал открываться.

Короткий порядок диагностики

Если в OpenCart появилась ошибка, я бы проверял так:

1. сохранить полный текст ошибки;
2. определить, где она появляется;
3. вспомнить последнее изменение перед сбоем;
4. проверить журнал OpenCart;
5. при серверной ошибке проверить PHP и веб-сервер;
6. определить фактические DIR_STORAGE и DIR_LOGS;
7. проверить config.php после переноса или изменения окружения;
8. если проблема появилась после модуля — проверить именно его;
9. проверить OCMOD и кеш, если они относятся к изменению;
10. при ошибке базы проверить параметры подключения;
11. при административной ошибке проверить права пользователя;
12. после исправления повторить исходное действие;
13. проверить витрину, админку, корзину и оформление заказа.

Так причина локализуется намного быстрее, чем при последовательной переустановке модулей, PHP и самого OpenCart.

Чего не стоит делать

При ошибке OpenCart не стоит сразу:

• переустанавливать весь магазин;
• заменять все файлы ядра;
• очищать наугад все каталоги сервера;
• удалять расширения без понимания причины;
• менять PHP и базу одновременно;
• править core-файлы только потому, что они указаны в traceback;
• скрывать ошибки и считать проблему исправленной;
• восстанавливать старую копию до того, как сохранён текст текущей ошибки;
• выполнять несколько исправлений одновременно.

Сначала зафиксируйте симптом, затем изменяйте по одной причине за раз.