We first wrote this post about the Joomla 6 alpha. Joomla 6 is now at 6.2, and we have moved our own site and several client sites to it, so here is the version we wish we had read then: the changes in Joomla 6 that break extension and template code, how to find them in a codebase, and the replacement for each.
Everything below was checked against the Joomla 6.2 source, not the release notes.
The short version
| Old code | Joomla 6 status | Use instead |
|---|---|---|
JFactory, JText, JHtml, JRoute … (≈450 aliases) | removed from core; only via the compat plugin, off on new installs | namespaced classes: Factory, Text, HTMLHelper, Route |
Joomla\CMS\Filesystem\File, Folder, Path | moved to the compat plugin | Joomla\Filesystem\File, Folder, Path |
Joomla\CMS\Input\Input | moved to the compat plugin | Joomla\Input\Input |
CliApplication scripts in /cli | moved to the compat plugin | a console command in cli/joomla.php |
$db->getQuery(true) | deprecated | $db->createQuery() |
Factory::getUser(), getDbo(), getCache() … | deprecated since 4.3, removed in 7.0 | $app->getIdentity(), the DI container |
chosen, wcpolyfill assets | removed (empty stubs in the compat plugin) | choices.js via the fancy-select field |
Legacy plugins (plgSystemFoo with method-name events) | still work, deprecated | SubscriberInterface + event objects |
The compatibility plugin: what it does and doesn't do
Joomla 6 ships Behaviour – Backward Compatibility 6 (plg_behaviour_compat6) with three options:
- Classes Aliases, off by default. It loads
classmap.php, which registers the oldJ*names. Every alias in it is tagged "6.0", meaning it was removed from core in 6.0. - Include Deprecated Classes, on by default. It registers
plugins/behaviour/compat6/classesunder theJoomla\CMSnamespace, which brings backFilesystem,Inputand the old CLIApplicationclasses. - Removed Assets, on by default. It adds empty
chosenandwcpolyfillassets so$wa->useScript('chosen')doesn't throw.
Two things we learned on real upgrades. First, a fresh Joomla 6 install has Classes Aliases off, so an extension that works on an upgraded site can fatal-error on a new one. Test on both. Second, these classes are tagged for removal in 7.0. The plugin buys you time, it doesn't fix anything. On our own site, two commercial extensions (a subscription component and a forum) still need the aliases on Joomla 6.2. That is the most common situation you'll meet.
Find the problems before you upgrade
Run this from the extension's root. It's crude, but it catches most of the list above in seconds:
# terminal
grep -rnE "\bJ(Factory|Text|Html|Route|Uri|Table|Model[A-Z]?\w*|View\w*|Controller\w*|Plugin|Log|Date|Language|Session|User|Access|Form\w*|Registry|Filter\w*)\b" --include=*.php .
grep -rnE "Joomla\\\\CMS\\\\(Filesystem|Input)\\\\" --include=*.php .
grep -rnE "getQuery\(true\)|Factory::(getUser|getDbo|getSession|getLanguage|getDocument|getCache)\(" --include=*.php .
grep -rnE "useScript\('(chosen|wcpolyfill)'|HTMLHelper::_\('formbehavior\.chosen" --include=*.php .
Then test with Debug System on and Log Deprecated API on (System → Global Configuration → Logging). Click through every view of the extension and read administrator/logs/deprecated.php. It lists each deprecated call with the file and line, including the calls that grep misses because the class name is built dynamically.
1. Class aliases: the mechanical part
// before – works only with "Classes Aliases" on
$user = JFactory::getUser();
$title = JText::_('MOD_EXAMPLE_TITLE');
$link = JRoute::_('index.php?option=com_example&view=items');
echo JHtml::_('date', $item->created, JText::_('DATE_FORMAT_LC3'));
// after – Joomla 4.0 and later
use Joomla\CMS\Factory;
use Joomla\CMS\HTML\HTMLHelper;
use Joomla\CMS\Language\Text;
use Joomla\CMS\Router\Route;
$user = Factory::getApplication()->getIdentity();
$title = Text::_('MOD_EXAMPLE_TITLE');
$link = Route::_('index.php?option=com_example&view=items');
echo HTMLHelper::_('date', $item->created, Text::_('DATE_FORMAT_LC3'));
Note getIdentity() instead of Factory::getUser(). Swapping JFactory for Factory makes the code run on Joomla 6, but every deprecated Factory::get* call is another fix waiting for Joomla 7. Do both in one pass.
2. Filesystem: same names, different behaviour
This is the one that causes bugs rather than fatal errors. The framework classes are not drop-in replacements: they throw exceptions where the old CMS classes returned false and queued an error message.
// before – Joomla\CMS\Filesystem\File
use Joomla\CMS\Filesystem\File;
if (!File::delete($tmpFile)) {
$this->setError('Could not remove the temporary file'); // never reached on Joomla 6
}
// after – Joomla\Filesystem\File (framework package)
use Joomla\Filesystem\Exception\FilesystemException;
use Joomla\Filesystem\File;
try {
File::delete($tmpFile);
} catch (FilesystemException $e) {
$this->getApplication()->enqueueMessage('Could not remove the temporary file', 'warning');
}
Also check File::exists() and Folder::exists(). In most code a plain is_file() or is_dir() is clearer and has no dependency.
3. Input: change the type hints
$app->getInput() is declared to return Joomla\Input\Input. Code that type-hints the old CMS class still runs while "Include Deprecated Classes" is on. With it off, or on Joomla 7, it fails with a TypeError.
// src/Helper/ExampleHelper.php
use Joomla\Input\Input; // was: Joomla\CMS\Input\Input
public static function getFilters(Input $input): array
{
return [
'category' => $input->getInt('catid'),
'search' => $input->getString('filter_search', ''),
];
}
While you're there, replace $app->input (a magic property) with $app->getInput(). Static analysis can follow a method call, not a magic property.
4. Database queries: createQuery()
getQuery(true) still works, but the $new parameter triggers a deprecation in the database package. createQuery() always returns a fresh query object:
// src/Model/ItemsModel.php
$db = $this->getDatabase();
$query = $db->createQuery() // was: $db->getQuery(true)
->select($db->quoteName(['id', 'title', 'alias']))
->from($db->quoteName('#__example_items'))
->where($db->quoteName('state') . ' = 1')
->order($db->quoteName('ordering') . ' ASC');
In models, use $this->getDatabase() (from DatabaseAwareTrait), not Factory::getDbo(). It also makes the model testable, because the database can be injected.
5. CLI scripts become console commands
Standalone scripts in /cli that extend CliApplication only run while the compat plugin provides that class. The supported way is a console command, registered by a plugin and run through cli/joomla.php. That gives you options, help text and exit codes for free:
// plugins/console/example/src/Extension/Example.php
namespace Example\Plugin\Console\Example\Extension;
use Example\Plugin\Console\Example\Command\CleanupCommand;
use Joomla\Application\ApplicationEvents;
use Joomla\Application\Event\ApplicationEvent;
use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\Event\SubscriberInterface;
final class Example extends CMSPlugin implements SubscriberInterface
{
public static function getSubscribedEvents(): array
{
return [ApplicationEvents::BEFORE_EXECUTE => 'registerCommands'];
}
public function registerCommands(ApplicationEvent $event): void
{
$event->getApplication()->addCommand(new CleanupCommand());
}
}
// plugins/console/example/src/Command/CleanupCommand.php
namespace Example\Plugin\Console\Example\Command;
use Joomla\Console\Command\AbstractCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Style\SymfonyStyle;
final class CleanupCommand extends AbstractCommand
{
protected static $defaultName = 'example:cleanup';
protected function configure(): void
{
$this->setDescription('Delete expired example items');
$this->addOption('days', null, InputOption::VALUE_REQUIRED, 'Older than N days', 30);
}
protected function doExecute(InputInterface $input, OutputInterface $output): int
{
$io = new SymfonyStyle($input, $output);
// … delete rows older than (int) $input->getOption('days')
$io->success('Done');
return Command::SUCCESS;
}
}
# terminal
php cli/joomla.php example:cleanup --days=60
For recurring jobs, a task plugin for the Scheduler is usually better than a command plus a crontab line, because it is configurable in the back end and logged. Commands are for things you run by hand or from a deploy script.
6. Assets: chosen is gone
If a form or layout calls HTMLHelper::_('formbehavior.chosen') or useScript('chosen'), Joomla 6 renders a plain <select>. Thanks to the stub asset there's no error, so it's easy to miss. Use the core fancy-select field, which is built on choices.js:
<!-- forms/filter_items.xml -->
<field
name="tag"
type="tag"
mode="nested"
layout="joomla.form.field.list-fancy-select"
multiple="true"
label="JTAG"
/>
7. Plugins: move to SubscriberInterface now
Legacy plugins (a plgSystemFoo class whose public methods are matched to event names) still run on Joomla 6. They are the next thing to go, and a plugin that implements SubscriberInterface works on Joomla 4.4, 5 and 6 alike, so there's no reason to wait. The full before/after, with the service provider and event objects, is in Joomla 6 plugin events explained with a CiviCRM example.
Template overrides
Overrides are code too. After the upgrade, open System → Templates → (your template) and look for the "Changes found" notice: Joomla flags overrides whose core layout changed in the update. In Joomla 6.2 the intro/full-text image layouts changed (separate image and figure classes), so overrides of layouts/joomla/content/intro_image.php and full_image.php are the first to compare.
A version policy that keeps one codebase
For our own extensions we support the current and the previous major version from one codebase: today Joomla 5.4 and 6.x, PHP 8.1+. Everything in this post works on both, because every replacement above exists since Joomla 4.x. The manifest says so:
<!-- mod_example.xml -->
<extension type="module" client="site" method="upgrade">
<name>mod_example</name>
<version>3.0.0</version>
<namespace path="src">Example\Module\Example</namespace>
…
</extension>
<!-- update XML -->
<targetplatform name="joomla" version="(5\.4|6)\..*"/>
<php_minimum>8.1</php_minimum>
Once your code passes the grep above and leaves deprecated.php empty, it is ready for Joomla 6 and most of the way to Joomla 7. What Joomla 7 removes next is in Joomla 7 breaking changes.
