Joomla Introduction and Architecture

Joomla is licensed under the GNU General Public License, version 2 or later. The entry-point files in the source tree carry the notice "GNU General Public License version 2 or later" and the copyright of Open Source Matters, Inc. In practice this means:

Open Source Matters, Inc. (OSM) is the non-profit organisation that provides the legal, organisational and financial resources of the project. It holds the trademarks and the project’s assets. The software itself is written by volunteers organised in teams, and the project is also supported by a large community of extension developers, translators, user group organisers and the people who run the events and the official magazine. The official documentation is now published in two places: the Joomla! User Guide (guide.joomla.org) for end users and the Joomla! Developer Manual (manual.joomla.org) for developers. The old wiki at docs.joomla.org is a legacy resource whose pages mark themselves obsolete, and several Manual pages (the lifecycle page, for example) are still stubs, so this page also reads the source tree on GitHub where the Manual says nothing.

Joomla has no built-in backup system and no built-in multisite mode. Backup extensions such as Akeeba Backup are third-party and belong to the ecosystem rather than to the core; see Backups and Recovery.

The web entry points are very short. They check the PHP version, define the guard constant _JEXEC and load includes/app.php of their own application. In the Site application that file does the following (the code below is shortened from the Joomla 6.2 source):

Source: Joomla CMS source: includes/app.php

The Administrator and Installation applications do the same with AdministratorApplication and InstallationApplication. The API entry point loads its own includes/app.php, and the console entry point skips that file and asks the container for the console application directly:

Source: Joomla CMS source: cli/joomla.php

Three things to notice:

A site that uses the optional public folder (see Installation and the Public Folder) keeps the code outside the web root and exposes only a small set of entry files, but the applications and the lifecycle below are unchanged.

Plugins are not separated by application. Installed and enabled plugins run in the Site, the Administrator and the API, so a plugin that should act in only one of them must test the application itself, for example with $this->getApplication()->isClient('site').

The sequence diagram shows a visitor opening the page of an alpine trail report, in which a menu item of type "Category Blog" shows articles of Trails > Alpine and the page contains a module in the sidebar-right position.

The Manual lists these application events, each backed by a concrete event class in the Joomla\CMS\Event\Application namespace (the two extension events live in Joomla\CMS\Event). A plugin subscribes to them by event name.

Source: Joomla Manual: Application events

The source code adds onBeforeExecute (dispatched by execute() before doExecute()), onAfterCompress and onError. Typical uses at Tallpine: a system plugin that adds a Content Security Policy in onAfterRender, one that redirects old trail URLs in onAfterRoute, and one that registers extra assets in onBeforeCompileHead. Chosen carelessly, work done in onAfterInitialise runs on every request including cached pages and the API, so it must stay cheap.

The API application follows the same outline with a different route step. Its route() imports the webservices plugin group and dispatches onBeforeApiRoute, which is where plg_webservices_tallpine registers its routes; it negotiates the response format from the Accept header, dispatches onAfterApiRoute, and then authenticates. Unless a route is marked public, authentication calls login() with the action core.login.api, and a failure throws an authentication error. Authentication is therefore part of routing and not a separate step. Dispatch then runs the component’s controller, whose view renders JSON:API. Fresh Joomla 6.2 installations have the API token plugin enabled and the Basic Auth API plugin disabled.

The Console application does not route a URL. It collects its commands (core commands and those contributed by plugins of the console group), runs one command and exits with a status code, which is why a command such as php cli/joomla.php tallpine:import can be used in cron jobs.

After installation the folders are scattered over the standard directories. The administrator and site parts of a component have separate folders, and the API part has its own:

The Manual documents these prefixes for the core:

Source: Joomla Manual: Joomla namespace prefixes

Third-party extensions use the same shape with their own vendor segment in place of Joomla. For Tallpine, the manifest line <namespace path="src">Tallpine\Component\Tallpine</namespace> yields these prefixes:

A module declares Tallpine\Module\NextHikes and gets Tallpine\Module\NextHikes\Site for modules/mod_tallpine_nexthikes/src. A plugin needs an extra segment for its group, for instance Tallpine\Plugin\Content\TallpineConditions, which maps to the src folder of the plugin directory under plugins/content.

Naming rules from the Manual: the vendor segment can be any name; components use the segment Component, modules Module, and plugins Plugin followed by the plugin group; the final segment should match the extension name; and capitalisation must match directory and file names exactly. A Windows laptop forgives a wrong case but a Linux server does not, so an extension that works on a developer machine can fail on the production server with a class-not-found error. Joomla does not validate the namespace during installation.

PSR-4 lookup compares the fully qualified class name with the list of registered prefixes, from the left. The prefix is removed and the remainder, with namespace separators turned into directory separators, is appended to the prefix’s directory. For example Tallpine\Component\Tallpine\Administrator\View\Trails\HtmlView becomes administrator/components/com_tallpine/src/View/Trails/HtmlView.php.

The loader is JLoader::loadByPsr, registered with spl_autoload_register in libraries/loader.php. The prefix map is not hard-coded. When the application initialises, Joomla scans the component, module and plugin directories of the site and the administrator, reads the <namespace> element of every manifest, and builds the prefix-to-directory map, which it caches in administrator/cache/autoload_psr4.php. That file also lists the prefixes of the installed extensions, which makes it the first thing to read when a class is not found. Library classes are not found by PSR-4; they use the Composer class map at libraries/vendor/composer/autoload_classmap.php.

Form XML needs a hint because XML has no namespace statement. A custom field or validation rule class is named on the <form> element with addfieldprefix and addruleprefix:

Source: Joomla Manual: Defining your namespace

Common mistakes with namespaces:

See Namespaces, Autoloading and Dependency Injection for the deeper treatment.

Each time Joomla boots an extension it creates a child container for that extension. set() writes to the child. get() looks in the child first and falls back to the parent, the main application container. This gives each extension its own private services while it can still use the core ones.

An extension describes its services in a file called services/provider.php, which returns a service provider. Loading an extension is two steps: the provider registers an extension class in the child container, and Joomla then gets that class from the container, which creates the instance. If the class implements BootableExtensionInterface, Joomla calls boot($container) immediately. The code in libraries/src/Extension/ExtensionManagerTrait.php does this for components, modules and plugins alike.

The provider for the Tallpine component registers the three factories the component needs and the extension class:

Source: Joomla Manual: Extensions and child containers

Common errors with providers: a provider that does not return the anonymous class (it must end with return new class implements ServiceProviderInterface), a typo in the factory namespace so the MVC factory builds the wrong class names, and registering an entry under a key the consumer never asks for. Providers run on every boot of the extension, so heavy work belongs in the closure, which is only executed when the service is requested.

The core extensions in the Joomla CMS repository, such as the services/provider.php file of com_content, are the best templates to compare against.