Joomla! Documentation™

WARNING BLOCK This guide assumes you are starting with Joomla 4.4.x. If you are on an earlier version, make sure you migrate or update to Joomla 4.4.x prior to upgrading to Joomla 5.x. /WARNING BLOCK

Introduction

Good news for Joomla 4.4.x to 5.x, it’s an upgrade, not a migration. Why? Two main reasons:

1. Joomla 4 (J4) extensions that have removed all deprecations of code and are using up-to date Joomla code, will work in Joomla 5 (J5)
2. Most others will work with the new Behaviour - Backward Compatibility Plugin enabled

This documentation reflects the simpler process by combining the planning and step by step in one document. Still, you will need some skills. Please see the Self Assessment to determine if you should or shouldn’t tackle the upgrade yourself.

INFO BLOCK Helpful links for third-party extension developers https://manual.joomla.org/migrations/44-50/removed-backward-incompatibility https://manual.joomla.org/migrations/44-50/new-deprecations https://manual.joomla.org/migrations/ /INFO BLOCK

Planning 4.4.x to 5.x

Hosting/Technical specification

1. Determine if your hosting environment meets the requirements.

You will not be able to upgrade to Joomla 5 if your server environment does not meet the technical requirements. The option to upgrade will not appear in the Joomla Update component.

• Minimum PHP8.1
• MySQL 8.0.13
• MariaDB 10.4.x (testing has shown that J3, J4, and J5, are compatible with MariaDB 10.4.x)

You can check your system information in Joomla 4 site by clicking System -> System Information. Contact your hosting provider if your server doesn’t meet the requirements.

PLANNING IMAGE FILE NAME System-Information.png (coming soon)

The following is an example of an environment that meets the technical requirements. It shows mysql 8.0.34, PHP8.1, and Joomla 4.4.x.

PLANNING IMAGE FILE NAME Good-System-Information.png (coming soon)

2. Check all of your extensions for compatibility with Joomla 5

There are a number of third-party extension scenarios for this upgrade.

1. The extension may be compatible with both J4 and J5 without the use of the backward compatibility plugin.
2. The extension may be compatible with both J4 and J5 WITH the use of the backward compatibility plugin.
3. The extension may appear to work in J5, but when you try to use it, it’s broken.
4. The extension may break the entire site.

Don’t worry! It’s not as bad as it sounds! First let’s talk about the backward compatibility plugin.

The Backward Compatibility Plugin

The Behaviour - Backward Compatibility Plugin is an attempt to allow third-party extensions to use classes no longer included in Joomla 5.

PLANNING IMAGE FILE NAME Backward-Compatibility-Plugin.png

When performing an upgrade from J4.4.x to J5, the backward compatibility plugin will be enabled automatically. New installations of J5 the backward compatibility plugin will be enabled by default.

The backward compatibility plugin that supports extensions that work in J4 will be in place through J5. In J6, the J4 extensions will not be made backward compatible with the plugin. This gives extension developers two additional years to make their extensions compatible with J5 without the backward compatibility plugin. The intention is that with every life cycle release, a backward compatibility plugin will support the life cycle before it until the life cycle after it.

Can you ever disable the backward compatibility plugin in J5? Great question. After determining that every single one of your third-party extensions are compliant and fully functional without the backward compatibility plugin enabled, you can disable the backward compatibility plugin. That said, we recommend using caution. Before you disable the backward compatibility plugin, doing one of the following two things is suggested:

1. Do it on a dev/test site. That way, if you accidentally missed one extension that makes your backend inaccessible, it doesn’t take your production site down.
2. Make sure you have access to the db. That way, you can enable the plugin again quickly if needed. More about this below.

Pre-update check vs. System -> Manage Extensions

Theoretically, the pre-update check would tell you if your third-party extensions are compatible with J5. However, the pre-update check is only helpful if all extension developers have made their extension reflect compatibility with their extensions. In a perfect world, the Extensions portion of the pre-update check would tell you if an extension either:

• Can be upgraded without the backward compatibility plugin enabled
• Can be upgraded with the backward compatibility plugin enabled
• If an update to the extension is required before upgrading from J4 to J5
• If an extension is incompatible completely

Testing has shown discrepancies between extensions that are compatible and are not compatible. This isn’t an issue with the pre-update check component. Rather, extension developers send information through their extensions which would populate the pre-update check correctly. If their extensions aren’t coded to tell the pre-update check the correct information, there’s very little (nothing) the pre-update check nor the Joomla! Project can do about it. A good source of information would be the third-party extension developer’s website to verify how the specific extension should be handled during the upgrade from J4 to J5.

The image below shows an example of the pre-update check component in Joomla 4.4.x of the Extensions section.

The top section will show the extensions that require an update. Please go to System -> Update -> Extensions and update your extensions.

The middle section shows extensions that the update information is unavailable from the extension developer. You will not know if these are compatible or not without testing them or contacting the developer.

The bottom section shows the extensions that have no update required. This means that the extensions are telling Joomla that they are compatible with Joomla 5. It is not specified if they require the backward compatibility plugin or not.

Please note that these extensions are not preferred by the CMS Release Team. These extensions are shown as an example only. They were randomly picked from the JED as a test.

IMAGE FILE NAME j4-Extensions-Pre-Update-Check-en.png

It is recommended to only use the Extensions portion of the pre-update check component as an extremely high level overview, but not the 100% source of truth. To say it another way, you may not be able to trust the pre-update check component depending on the extensions you are using.

What is the source of truth then? Systems -> Manage Extensions

IMAGE FILE NAME j4-System-Manage-Extensions-en.png

From the Extensions: Manage screen, you will be able to see all of the third-party extensions you are using on the site. In the screenshot below you see the main screen. In the Author column, you can see a popular extension developer’s name in a number of rows. You can also see the Author of the Joomla Project in a number of rows.

IMAGE FILE NAME j4-Extensions-Manage-en.png

Check your third party extensions. You’ll next be determining if they are compatible with J5 (with or without the backward compatibility plugin) or not. If they’re not, the upgrade will be unsuccessful.

Three ways to check your third-party extensions for J5 compatibility

1. Check the developer website.
2. Take a backup/copy of your J4 site, restore it on a subdomain, turn on debug, follow the step by step (below) to upgrade to J5. See if anything breaks. If it does break, disable each extension that throws an error making note of the extension. You’ll need to contact the developer about it since it isn’t compatible with J5.
3. Install a clean J5 package on a subdomain, enable the Behaviour - Backward Compatibility Plugin, install all the extensions you use and see if they work.

NOTE: The Joomla! Extensions Directory JED will only display a Joomla 5 compatible badge for extensions that are compatible without the use of the backward compatibility plugin.

You could do a combination of the above. Start with a clean install and test out your extensions. When you know which ones do or don’t work, you can work with the developers to see where they’re at with their development for J5. THEN, once all your extensions work in a clean site, you’ll know you can test a full upgrade from J4.4.x to 5.x.

You may want to determine if an extension works without the backward compatibility plugin enabled. If that’s the case, you’ll want access to the database. Plan for it. Make sure you have access to the database.

When you initially install J5, the backward compatibility plugin will be disabled. Install each extension one at a time. If it kills your site, enable the backward compatibility plugin via the database.

The Backward Compatibility Plugin can be found in the database in the _extensions table. It’s called plg_behaviour_compat. Set the Enabled field to 0 to disable the plugin. 1 to enable the plugin. By enabling the backward compatibility plugin again, you may gain access to the backend of Joomla again (as long as the extension works with the backward compatibility plugin).

OR

You can disable the extension in the database so that you can continue testing your other extensions to see if they will function without the compatibility plugin enabled. These entries will be in the #_extensions table. You’ll change the Enabled field to 0 to disable the extension.

In some cases, when you install an extension in J5 that isn’t compatible with or without the backward compatibility plugin enabled, you will need to find the entries in the database for that extension (there may be a few or many of them) and disable them until you can regain access to the backend. These entries will be in the #_extensions table. You’ll change the Enabled field to ) to disable the extension. Once you can access the backend of Joomla again, you can uninstall it properly from System -> Manage -> Extensions and inquire with the developer.

Cassiopeia, Recaptcha, Weblinks, Schema.org, and Search (com_search not Smart Search)

Cassiopeia

Cassiopeia will remain the frontend template for Joomla 5. Your customisations should be fine, still, we recommend testing on a dev site to make sure. Bootstrap will be upgraded to Bootstrap 5.3 in Joomla 4.4.0. If there are Bootstrap discrepancies in your template, they will already be visible in 4.4.0. Thus, most, if not all issues would be found prior to upgrading to J5.

Google reCAPTCHA

If you are using Google reCAPTCHA in J4, you should replace it with Invisible reCAPTCHA prior to upgrading to Joomla 5 (or a third-party solution). J5 will not include Google Recaptcha any longer. The Recaptcha plugin will be uninstalled upon upgrade to J5. The Invisible reCAPTCHA plugin still exists if you’ve upgraded from 4.4.x. You can enable it and set it up with new keys so you can use Invisible reCAPTCHA instead. Or you may use another third-party solution. Fresh installations of Joomla 5.x do not include any reCAPTCHA plugins in the core. Fresh installations of Joomla 5.x will need to use a third-party plugin/solution.

com_weblinks

At the time of this writing (September 2023), the Weblinks extension works in J5 with the backward compatibility plugin enabled. Weblinks will not work without the backward compatibility plugin being enabled. Most likely, J5 will be the last Joomla life cycle that weblinks will be available.

Schema.org Plugin

With Joomla! 5 a new and more dynamic way of handling rich snippets (based on https://schema.org/) data was implemented. By default they are set up in a way that the information for search engines is the same as in Joomla 4, but to customize the output, please go to System => Manage => Plugins and search for the system plugin “Schema.org - System”. Edit the plugin to add your site information for a proper usage of the functionality. Read more about Rich Snippets in this magazine article.

com_search

com_search is not available in Joomla 5. Uninstall it before upgrading to Joomla 5. You will now use Smart Search (com_finder).

Trial run

As part of your planning, it’s recommended to test your upgrade on a subdomain or locally to determine it works perfectly. Make sure you keep track of any steps you need to take for your upgrade to take place perfectly.

Once you’ve tested your upgrade on a subdomain or localhost, and it works perfectly, you can take a backup of your production site and perform the upgrade to it. Step by step instructions are below.

I'm nowhere near done. To be continued. Thanks for your patience.