Joomla 6 upgrade: check your extensions first

Joomla core moves from 5 to 6 without much trouble. The extensions are what break: a module that still calls JFactory, a plugin that reads Joomla\CMS\Filesystem\File, a template override written for Joomla 3. The core gives you two tools to find them before you click Update, and one switch to keep old code running for a while. You can go through each extension by hand, or let our own free Code Checker read the code for you. Both routes are below.

Before anything else: PHP 8.3 and a backup

Joomla 6 will not start on anything older than PHP 8.3.0. Check the version under System, System Information, and switch it in your hosting panel before the upgrade, while Joomla 5 is still running. Joomla 5.4 runs fine on 8.3, so you can test that step on its own. More on picking a version in Update to the latest PHP version.

Then make a full backup that you can restore without the host's help, and ideally a copy of the site on a subdomain to try the upgrade on first. Why the host's own backup is not enough is explained in Backups: the one your host keeps is not yours.

Step 1: the Pre-Update Check in Joomla Update

Update Joomla 5 to its latest 5.4 release first. Joomla 6 is only offered from there. If System, Update, Joomla does not show 6.x, open Options in that screen and look at the Update Channel: Default only offers a new major version once the project switches it on, and Joomla Next shows it earlier.

When 6.x is offered, Joomla shows a Pre-Update Check for Joomla 6.x before the update button. It has three parts:

• Required Settings: PHP version, database version and PHP extensions. Anything red here stops the upgrade.
• Recommended Settings: php.ini values such as output buffering. Not blocking, but worth fixing.
• Extensions: every non-core extension, sorted by what its update server says about Joomla 6.

The extension list is the important part. Read the groups like this:

• No Update Required: the developer states that the installed version works on Joomla 6.
• Update Required: a newer version supports Joomla 6. Install that update first, on Joomla 5.
• Update Information Unavailable or Missing Compatibility Tag: Joomla cannot tell. This includes every extension without an update server, and every custom module someone wrote for you years ago. These are the ones to check yourself.

Joomla also flags plugins that could break the update process itself under Potential Upgrade Issue. Disable those before you go on. You can tick the box to acknowledge the warning and continue anyway, but on a live site that is a gamble.

Step 2: check the code of the unknown extensions

For the extensions in the "unknown" groups, the question is simple: does the code use anything Joomla 6 removed? Three things to look for in the PHP files:

Old Joomla 3 class names

JFactory, JText, JHtml, JRoute and the rest of the J-prefixed classes. In Joomla 4 and 5 they still worked through aliases. In Joomla 6 those aliases are off unless you switch them on (see step 3). Their replacements are the namespaced classes, for example Joomla\CMS\Factory and Joomla\CMS\Language\Text.

Classes removed in Joomla 6

Code that uses Joomla\CMS\Filesystem\File, Folder or Path, or Joomla\CMS\Input\Input, only runs as long as the backward compatibility plugin supplies a copy. The replacements are the Joomla Framework packages: Joomla\Filesystem\File and Joomla\Input\Input.

Calls that will go in Joomla 7

Factory::getDbo() and $app->input still work in 6, but are deprecated. If you are fixing an extension anyway, fix these too, so you do not have to come back for the next major version.

For one small module you can do this with a grep -rnE "JFactory|CMS.Filesystem|CMS.Input" modules/mod_yourmodule on the server. For twenty extensions it gets slow, and grep also counts mentions in comments.

A clean report means none of the known old code was found. It does not run the extension, so still test it on a copy of the site.

Step 3: Behaviour - Backward Compatibility 6

Joomla 6 ships a plugin called Behaviour - Backward Compatibility 6 (System, Plugins, filter on "compat"). It keeps code written for Joomla 5 running. It has two options:

• Include Deprecated Classes (on by default): loads copies of removed classes, such as the old Filesystem and Input classes, from plugins/behaviour/compat6/classes/.
• Classes Aliases (off by default): registers the old J-prefixed names such as JFactory and JText. Switch this on when an old extension throws "Class JFactory not found" after the upgrade.

Treat this plugin as a bridge, not a fix. The code in it says the classes it supplies will likely be removed in Joomla 7. Make a list of the extensions that need it and replace or update them while you have time.

Step 4: upgrade the copy, then test

Run the upgrade on the copy first. Then go through the pages that use each third-party extension, the forms, the login and the administrator screens of those extensions. Switch on Debug System in Global Configuration while you test: a white page or a 500 error then shows the real message. How to read it is in Joomla's debug console.

Does something break that you cannot fix? Disable that extension, finish the upgrade and replace it later. If a site has too many custom parts to check yourself, Cloudfaction, the agency behind this site, does Joomla upgrades and migrations.

Checklist

• PHP 8.3 or newer, switched and tested on Joomla 5.4
• Full backup you can restore yourself, plus a test copy
• Joomla 5 updated to the latest 5.4 release, all extensions updated
• Pre-Update Check: Required Settings green, plugins under Potential Upgrade Issue disabled
• Extensions without compatibility information checked for old code, by hand or with our free Code Checker
• Backward Compatibility 6 options set, and a list of the extensions that still need it
• Upgrade done on the copy and tested with Debug System on, then on the live site