Оновлення 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