The Joomla Compatibility Plugin: when do you still need it?

You want to upgrade a Joomla 5 site to Joomla 6. Everything seems ready for Joomla 6, the server meets the requirements and your extensions have been updated. But then you come across Behaviour - Backward Compatibility in the plugin list. And from Joomla 5.4 onwards, Behaviour - Backward Compatibility 6 is also listed there.

Should these plugins be enabled or disabled? And more importantly: how do you know if your website actually still needs them?

Fortunately, the answer is fairly simple, as long as you realise that we’re talking about two different plugins.

Why does the Compatibility Plugin exist?

With a new major version of Joomla, old, obsolete code is eventually removed. Extensions that still use that old Joomla code may therefore suddenly start causing errors. The Compatibility Plugin temporarily bridges the gap between the old and new situations. This is handy. It means you don’t have to wait until every extension has been fully updated before you can upgrade to a new version of Joomla.

However, it is a temporary solution.

An extension is only truly compatible with a Joomla version when it works without the associated Compatibility Plugin.

There are two plugins for the upgrade from Joomla 5 to 6

This is probably the most important thing to know.

In Joomla 5.4, you may come across two plugins:

• Behaviour - Backward Compatibility
• Behaviour - Backward Compatibility 6

The first is the old compatibility layer that helps Joomla 4 code run under Joomla 5. The second has already been added to Joomla 5.4 so that Joomla 5 code can be supported under Joomla 6 in future.

In Joomla 5.4, Backward Compatibility 6 does not yet do anything itself. It is already in place so that it can start working as soon as Joomla is updated to version 6.

Before upgrading to Joomla 6, the old plugin must be removed from

Before upgrading from Joomla 5.4 to Joomla 6, Behaviour - Backward Compatibility must be disabled. This is not merely a recommendation. Joomla’s pre-update check verifies this. At the same time, Behaviour - Backward Compatibility 6 must be correctly installed and enabled.

In short: Joomla 5.4 before the upgrade

• Behaviour - Backward Compatibility → OFF
• Behaviour - Backward Compatibility 6 → ON

If you can’t disable the first plugin without causing things to break, then your site isn’t ready for Joomla 6 yet.

And that’s actually a very useful test.

How do you find out which extensions still require the old plugin?

It’s best not to do this on your live website for the first time. Make a copy of the site and, in Joomla 5.4, disable Behaviour - Backward Compatibility on that copy. Then test the website thoroughly. Don’t just take a quick look at the homepage. Also go through the sections controlled by extensions:

• forms;
• search functions;
• online shops;
• user login;
• modules;
• custom fields;
• multilingual support;
• CLI tasks and cron jobs;
• plugins running in the background;
• and, of course, the admin area.

If necessary, enable Joomla Debug whilst testing and also check your PHP error log.

If, for example, after disabling it you receive an error about a non-existent class, method or other legacy Joomla code, you have probably found an extension that still depends on the compatibility layer. Update that extension or contact the developer.

If you’ve written custom code yourself, you’ll know who to call. 😉

Next, on to Joomla 6

Is your entire Joomla 5.4 site working without the old Compatibility Plugin? Great. You’ve then cleared a major hurdle on the way to Joomla 6. You can then run the standard Joomla pre-update check and test the upgrade to Joomla 6.

The plugin Behaviour – Backward Compatibility 6 remains enabled during that upgrade. In Joomla 6, this ensures that extensions which still use certain Joomla 5 code can continue to function for the time being.

This brings you to the next question.

Does Joomla 6 still need the Compatibility Plugin?

Perhaps.

• After the upgrade, you can test whether your Joomla 6 site works without Behaviour - Backward Compatibility 6.
• Do this again in a test environment.
• Disable the plugin and test the frontend, administrator panel and key functionality. Also check your logs.
• Is everything working?
  • If so, you can generally leave the plugin disabled.
• Is something going wrong?
  • If so, re-enable it and find out which extension is using the old code.

The fact that an extension works on Joomla 6 does not automatically mean that it does not need the Compatibility Plugin.

That distinction is important.

Why would you disable it if everything is working fine?

You might think: just leave that plugin enabled.

That’s fine for a while. That’s what it’s designed for.

But you’re just postponing the problem.

My practical approach

When upgrading from Joomla 5 to Joomla 6, I would therefore follow this sequence:

• First, update to the latest Joomla 5.4 version.
• Update all extensions.
• Create a thorough backup.
• Ideally, set up a separate test environment.
• Disable Behaviour – Backward Compatibility.
• Test the front-end, administrator panel, extensions, customisations and background tasks.
• Resolve any issues before proceeding.
• Check that Behaviour – Backward Compatibility 6 is enabled.
• Run the Joomla pre-update check.
• Upgrade the test site to Joomla 6.
• Test thoroughly again.
• Then, for testing purposes, disable Backward Compatibility 6.
• Is everything still working? If so, you can leave it disabled.

The compatibility layer is intended as a temporary measure, not a permanent solution. Joomla will eventually remove the old compatibility code. An extension that continues to function solely thanks to such a plug-in will therefore need to be updated sooner or later.

That is why I regard the plug-in primarily as a handy technical checklist:

Can my site run without the compatibility plug-in?

Yes? Then you know that your extensions and customisations are, technically speaking, much better suited to the current generation of Joomla.

No? Then you know where there is still work to be done.

Make sure you have access to the database

One more practical tip before you start experimenting. Make sure you have access to the database. If an extension causes a fatal error after the plugin has been disabled, you may no longer even have access to /administrator.

The Joomla 6 compatibility plugin is listed in the #__extensions table as: plg_behaviour_compat6. You can reactivate it by resetting the ‘enabled’ field to 1. For the old Joomla 5 compatibility plugin, this is: plg_behaviour_compat

You can also temporarily disable individual extensions via #__extensions if a problem is blocking the entire backend.

It’s not the most elegant solution, but it’s particularly useful when your administrator panel suddenly only displays an error message.

So the latter doesn’t necessarily have to happen on the same day as the upgrade.

The most important thing is that you know why the plugin is still enabled.

Compatibility is not the end of the line

The Compatibility Plugin is a clever way for Joomla to make upgrades between major versions less painful. But don’t regard it as proof that all extensions are fully Joomla 6-compatible. In fact, it’s exactly the opposite.

The best test for Joomla 6 compatibility is a Joomla 6 site that runs smoothly whilst Behaviour – Backward Compatibility 6 is disabled.

If that works, you no longer need the compatibility layer. And that is exactly where you ultimately want to be.