Joomla Compatibility Layer

With the release of Joomla 3.8 a first compatibility layer for Joomla 4 was released. What does this layer contain? Why is such a layer needed? Questions like this will be answered in this post.


A big change in Joomla 4 are namespaces, a feature which exists since PHP 5.3.0, released in 2009. The whole PHP community has fully adapted to it and Joomla doesn’t want to fall behind.

In Joomla 4.0, the core architecture will be supporting and largely using namespaced PHP code. This applies for the core libraries and extensions.

Why a migration layer

We have a promise that a Joomla 3 extension will run on Joomla 4 and a namespaced Joomla 4 extension on Joomla 3.9. To achieve that, we decided to go step by step to reduce the risk of bugs and to give the extension developers enough time for adaption. The first step was to namespace the libraries folder in Joomla 3.8. This means that classes like JForm now have the class name \Joomla\CMS\Form\Form. To keep backward compatibility, the old class names do still work. That’s the migration layer we were talking about.

Classes which still do exist in the folders /libraries/cms, /libraries/joomla and /libraries/legacy are mostly deprecated or removed in Joomla 4. There is one exception, the filesystem package. We didn’t have enough time to convert it for the 3.8.0 release. It will be done then in 3.9.

What should I do with my new extension?

If you plan to do a new extension for Joomla 3, then you still need to do it the old way. You can use the namespaced libraries classes, but the extension, primarily the component, still needs to be NOT namespaced. We will backport most of the Joomla 4 features in 3.9.0 as 3.8 is in bug fix mode now.

Current status of Joomla 3.9

We didn’t start yet to backport the features from Joomla 4 to 3.9 as there are some issues we need to fix in 4 before we can start developing against 3.9. It means that it is not recommended to work against Joomla 3.9 yet.


The full Joomla 4 roadmap is published on the Developer site. If you want to have a look on the latest code, you can test the nightly builds.

Questions should be asked in the developer mailing list, but most of the backward compatibility issues are explained here.