Joomla! Programmers Documentation

A Joomla instance contains thousands of PHP source files, with a comparable number of PHP classes. it's obviously impractical to do a require of every source file, to make the PHP interpreter aware of all the classes. How then can Joomla avoid getting a PHP Class not found fatal error when it tries to access a class which the PHP interpreter doesn't recognise? The answer is that it uses class autoloading.

When Joomla initialises it sets up (in libraries/loader.php setup()) a number of autoloaders using, for example:

spl_autoload_register(['JLoader', 'loadByPsr']);

If the PHP interpreter encounters a line such as:

if (class_exists($classname)) ...

and it doesn't recognise the name of the class then it will pass the class name to a registered autoloader and will call eg

loadByPsr($classname)

passing the name of the class. From Joomla 4 onwards this should be a fully qualified classname.

The responsibility of the autoloader is to try and find the source file which contains that class, and perform an include_once on it, so that PHP then becomes aware of that class. For components, modules and plugins (both Joomla and third party extensions) Joomla uses the PSR4 method of mapping class names to source files.

During initialisation Joomla looks through the components, modules and plugins directories for both the site and the administrator to find all the manifest XML files. It then loads the XML and looks for <namespace> elements, and from those elements builds a set of mappings of namespace prefixes to directories. As this involves quite a bit of work the result is cached in administrator/cache/autoload_psr4.php - go ahead and have a look at it!.

The loadByPsr function then uses this mapping and the PSR4 rules for finding source files described in Finding classes with PSR4 to determine the name of the file which should contain that class. It checks if the file exists and if so performs include_once on it, and returns.

If the autoloader loadByPsr function has successfully found the class, then PHP treats the class_exists($classname) expression as now true, and continues down the code. If it was unsuccessful then PHP raises the class not found exception.

Joomla has a number of autoloader functions - not all classes are loaded using PSR4. For example libraries classes all have a mapping of FQN to the individual source file for that class - have a look through libraries/vendor/composer/autoload_classmap.php.

There is also a mapping (in libraries/classmap.php) from old global library names starting with J (eg JModelAdmin) to the FQN equivalents, but this disappears in Joomla 6.