Product SiteDocumentation Site

1.4. Class Auto-loading

The Joomla Platform implements a class auto-loader removing the need for the developer to include files by hand, or by using a fall to the jimport function (this is now discourage in favor of using JLoader::register). Only class names that begin with upper case "J" will be considered for auto-loading. Following the "J" prefix, the class name must be in camel case and each segment of the name will represent a folder path below JPLATFORM_PATH/joomla where the last segment of the name is the name of the class file. If there is only one part to the class name, the auto-loader will look for the file in a folder of the same name. Folder names must be in lower case.
Example 1.3. Valid auto-loading cases
JDatabase should be located in JPATH_PLATFORM/joomla/database/database.php
JDatabaseQuery should be located in JPATH_PLATFORM/joomla/database/query.php
JDatabaseQueryMysql should be located in JPATH_PLATFORM/joomla/database/query/mysql.php

There is no limit to the depth to which the auto-loader will search, providing it forms a valid path based on the camel case natural of the class name. Note that while acronyms and names such as HTML, XML and MySQL have a standard presention in text, such terms must observe camel case rules programmatically ("HTML" becomes "Html", "XML" becomes "Xml" and so on).
The JLoader class allows additional customisation including, but not limited to, providing the ability to override core classes and cater for classes that do not conform with the auto-loader naming and path convention.

1.4.1. JLoader

JLoader is the mainstay of the Joomla Platform as it controls auto-loading of classes. Wherever possible, class names and paths should conform to the auto-loader convention in the form:
JClassname located in JPATH_PLATFORM/joomla/classname/classname.php, or
JPathtoClassname located in JPATH_PLATFORM/joomla/pathto/classname.php
However, deviations, and even overrides can be handled by JLoader's register and discover methods.

1.4.1.1. Registering Classes

New classes, or override classes can be registered using the register method. This method takes the class name, the path to the class file, and an option boolean to force an update of the class register.
Example 1.4. Using JLoader::register
// Register an adhoc class.
JLoader::register('AdhocClass', '/the/path/adhoc.php');

// Register a custom class to override as core class.
// This must be done before the core class is loaded.
JLoader::register('JDatabase', '/custom/path/database_driver.php', true);

1.4.1.2. Registering a Class Prefix

Since 12.1, there is the ability to register where the auto-loader will look based on a class prefix (previously only the "J" prefix was supported, bound to the /libraries/joomla folder). This allows for several scenarios:
A developer can register the prefix of custom classes, and a root path to allow the auto-loader to find them.
A developer can register an extra path for an existing prefix (for example, this allows the Joomla CMS to have custom libraries but still using the "J" prefix).
A developer can register a force override for a prefix. This could be used to completely override the core classes with a custom replacement.
Example 1.5. Using JLoader::registerPrefix
// Tell the auto-loader to also look in the /libraries/cms folder for "J" prefixed classes.
JLoader::registerPrefix('J', JPATH_PLATFORM . '/cms');

// Tell the auto-loader to look for classes starting with "Foo" in a specific folder.
JLoader::registerPrefix('Foo', '/path/to/custom/packages');

// Tell the auto-loader to reset the "J" prefix and point it to a custom fork of the platform.
JLoader::registerPrefix('J', '/my/platform/fork', true);

1.4.1.3. Discovering Classes

Classes in a folder that follow a naming convention, but not one the auto-loader immediately recognises, can be registered collectively with JLoader's discover method. The discover method looks at the file names in a folder and registers classes based on those names. Additional arguments can be used to update the class register and recurse into sub-folders.
Example 1.6. Using JLoader::discover
// Register all files in the /the/path/ folder as classes with a name like:
// Prefix<Filename>
JLoader::discover('Prefix', '/the/path/');