Обновление Joomla 5.4 до Joomla 6: типовые проблемы и диагностика

Само ядро Joomla обновляется автоматически, включая изменения структуры базы данных. Основной источник проблем — код, который не является частью актуального ядра Joomla:

• сторонние компоненты, модули и плагины;
• шаблоны;
• template overrides;
• собственные расширения и интеграции;
• устаревшие Joomla API;
• код, несовместимый с текущей версией PHP;
• нестандартные изменения базы данных или файлов ядра.

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

Joomla 6 имеет более высокие системные требования, чем предыдущие основные версии. Перед обновлением проверьте окружение через Система → Информация о системе и сравните его с актуальными требованиями Joomla.

Для Joomla 6 также необходимы PHP-модули json, simplexml, dom, zlib, gd и драйвер для работы с поддерживаемой базой данных. Рекомендуемый PHP memory limit — не менее 256 МБ.

В Joomla 5.4 одновременно могут присутствовать два разных плагина совместимости. Их не следует путать.

Эти условия проверяются Joomla во время Pre-Update Check. Если старый плагин совместимости Joomla 5 включён или плагин Backward Compatibility 6 отключён, штатное обновление до Joomla 6 не должно продолжаться.

На практике наиболее важная проверка выполняется ещё на Joomla 5.4: отключите Behaviour - Backward Compatibility и протестируйте сайт. Если после этого появляются ошибки, некоторые расширения всё ещё зависят от устаревшего API Joomla.

Компоненты, модули и плагины являются наиболее частой причиной проблем после обновления. То, что расширение работает в Joomla 5, само по себе не означает полной совместимости с Joomla 6.

Перед обновлением:

• обновите все сторонние расширения;
• проверьте заявленную разработчиком поддержку Joomla 6;
• удалите расширения, которые больше не используются;
• проверьте сайт Joomla 5.4 с отключённым старым Backward Compatibility;
• выполните пробное обновление на staging-копии.

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

Даже если сам шаблон заявлен как совместимый с Joomla 6, старые template overrides могут содержать код из предыдущих версий Joomla.

После обновления проверьте:

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

Если проблема появляется только на frontend, временное переключение на стандартный шаблон Joomla поможет быстро определить, связана ли она с шаблоном или его overrides.

Для переопределённых файлов недостаточно просто проверить PHP-синтаксис. Необходимо сравнить старый override с актуальным файлом layout или view в Joomla 6 и перенести в новую версию только необходимые изменения.

После перехода могут появиться следующие сообщения:

• Class ... not found;
• Call to undefined method ...;
• Undefined property ...;
• TypeError;
• сообщения о deprecated API;
• HTTP 500 без подробного сообщения.

В первую очередь обратите внимание на путь к PHP-файлу в stack trace. Например, путь внутри /plugins/, /components/, /modules/ или каталога шаблона часто сразу показывает, какое расширение вызвало ошибку.

Для собственного кода необходимо сверять используемые API с документацией Joomla 6. В Joomla 6 часть устаревших API удалена или перенесена в плагин совместимости.

Например, старый namespace файловой системы:

use Joomla\CMS\Filesystem\File;
use Joomla\CMS\Filesystem\Folder;

в новом коде следует заменять на Joomla Framework Filesystem:

use Joomla\Filesystem\File;
use Joomla\Filesystem\Folder;

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

if (is_file($filePath)) {
    // File exists
}
if (is_dir($directoryPath)) {
    // Directory exists
}

Другой пример касается Input. Namespace Joomla\CMS\Input в Joomla 6 перенесён в слой обратной совместимости. Новый код должен использовать пакет Joomla Framework:

use Joomla\Input\Input;

Если вместо страницы отображается белый экран или HTTP 500, необходимо найти исходную PHP-ошибку.

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

Также проверьте:

• PHP error log;
• журналы веб-сервера;
• каталог журналов Joomla;
• stack trace сообщения об ошибке.

Если Administrator также не открывается, наиболее полезным источником информации обычно будет PHP error log на сервере.

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

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

Система → Обслуживание → База данных.

Если Joomla сообщает о проблемах структуры, воспользуйтесь штатной командой Update Structure.

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

HTTP 500 после обновления — это симптом, а не конкретная причина. Чаще всего за ним стоит PHP Fatal Error.

Последовательность диагностики:

1. Откройте PHP error log.
2. Найдите первую fatal error, соответствующую проблемному запросу.
3. Проверьте файл и строку, указанные в сообщении.
4. Определите расширение или шаблон, которому принадлежит файл.
5. Обновите или временно отключите проблемное расширение.
6. Повторите проверку.

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

Если страница открывается, но перестали работать меню, модальные окна, вкладки, галереи или другие интерактивные элементы, проверьте браузерные DevTools.

Во вкладках Console и Network обратите внимание на:

• JavaScript exceptions;
• 404 для JS или CSS;
• ошибки загрузки модулей;
• конфликты старых JavaScript-библиотек;
• файлы шаблона или сторонних расширений, которые не загрузились.

После обновления шаблона или JavaScript-файлов очистите:

• кеш Joomla;
• кеш браузера;
• server-side cache;
• CDN cache, если используется.

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

После обновления проверьте не только то, открывается ли главная страница. Для реального сайта важно протестировать все основные типы URL.

• пункты главного меню;
• материалы;
• категории;
• поиск;
• контакты;
• авторизацию и регистрацию;
• страницы сторонних компонентов;
• старые URL, на которые существуют внешние ссылки.

Если конкретный URL перестал работать, проверьте тип соответствующего пункта меню, состояние связанного расширения и его routing. Не изменяйте структуру URL без необходимости только из-за самого факта перехода на Joomla 6.

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

1. Прочитайте точную ошибку. Определите файл, класс, метод или таблицу.
2. Проверьте PHP и server logs. Особенно если видите только HTTP 500.
3. Определите владельца проблемного файла. Joomla core, шаблон, стороннее или собственное расширение.
4. Обновите проблемное расширение. Проверьте версию для Joomla 6.
5. Временно отключите подозрительное расширение. Желательно на staging-копии.
6. Проверьте шаблон и overrides. При необходимости протестируйте стандартный шаблон.
7. Проверьте структуру базы данных.
8. Очистите кеши.
9. Повторно протестируйте frontend и Administrator.

Лучший способ устранения проблем обновления — найти большинство из них ещё на Joomla 5.4.

• Обновите Joomla до актуальной версии ветки 5.4.x.
• Сделайте полную резервную копию файлов и базы данных.
• Проверьте, что резервная копия действительно восстанавливается.
• Создайте staging-копию сайта.
• Проверьте серверные требования Joomla 6.
• Обновите все сторонние расширения.
• Удалите ненужные расширения.
• Проверьте Joomla 6 compatibility у разработчиков расширений.
• Проверьте шаблон и template overrides.
• Проверьте собственный PHP-код.
• Отключите Joomla 5 Behaviour - Backward Compatibility и протестируйте Joomla 5.4.
• Убедитесь, что Behaviour - Backward Compatibility 6 установлен и включён.
• Проверьте результаты Pre-Update Check.
• Выполните полное тестовое обновление staging-сайта.

После успешного перехода на Joomla 6:

• откройте frontend и Administrator;
• проверьте основные пункты меню;
• проверьте создание и редактирование материалов;
• протестируйте формы и отправку email;
• проверьте поиск;
• протестируйте сторонние компоненты;
• проверьте Система → Обслуживание → База данных;
• просмотрите PHP и Joomla logs;
• очистите кеш;
• отключите Debug и расширенное отображение ошибок после завершения проверки.

Если после обновления возникла критическая проблема, а её причина не определяется сразу, безопаснее восстановить протестированную резервную копию и продолжить поиск на staging-сайте, чем ремонтировать production без возможности быстрого отката.

Плагин Behaviour - Backward Compatibility 6 позволяет части старого кода продолжать работать в Joomla 6. Это полезный переходный механизм, но его не следует рассматривать как замену обновлению кода.

Например, некоторые API, удалённые из основного Joomla 6 core, доступны только через этот слой совместимости. К ним относится часть старого Joomla\CMS\Filesystem и Joomla\CMS\Input.

Для стороннего расширения временная зависимость от Backward Compatibility может быть допустимой, если это прямо поддерживается его разработчиком. Собственный код лучше постепенно перевести на актуальные Joomla Framework и CMS API.

Основная причина проблем при переходе Joomla 5.4 на Joomla 6 — не сам механизм обновления, а сторонний или собственный код, который зависит от устаревших API.

Поэтому надёжный процесс состоит из трёх этапов: проверить совместимость ещё на Joomla 5.4, выполнить обновление на staging-копии и только после полного тестирования повторить его на production.

Если проблема всё же возникла, начинайте не со случайного редактирования файлов, а с конкретного сообщения об ошибке, PHP/server logs и определения расширения или шаблона, которому принадлежит проблемный код.

Использованные источники:
Joomla! Documentation — Joomla 5.4.x to 6.x Planning and Upgrade Step by Step
Joomla! Programmers Documentation — Technical Requirements
Joomla! Programmers Documentation — Compatibility Plugins
Joomla! Programmers Documentation — Removed and Backward Incompatibility
Joomla! Programmers Documentation — Joomla 5.4 to 6.0 Upgrade Notes
JoomTech Solutions — Joomla 6 Migration Problems: Common Issues & Fixes