Dionysopoulos.me

Before Joomla 4.0 all plugins were a single class which followed the naming convention PlgFolderName where Folder is the plugin folder with its first letter capitalised (e.g. System for system plugins) and Name is the plugin's name with all of its letters lowercase except the first one which is capitalised (e.g. Example). Thus a plugin named example in the system folder would have the class name PlgSystemExample.

In those earlier Joomla versions the file name of the plugin was also prescribed and could not change. The aforementioned plugin's class file would necessarily be plugins/system/example/example.php. The immediate result of that is that the file name and the class name are not the same which makes class autoloading for plugins a pain in the posterior. Therefore, we had no autoloading for plugins.

While this is not a problem for trivial plugins, it can become a substantial issue for more complex plugins. As a developer you either had to create a supermassive class running into the several thousands of lines of code or you'd have to “invent” your own autoloader. Typically it would be the latter, with the plugin's constructor method using \JLoader::register or \JLoader::registerPrefix to register individual, arbitrarily named classes or a PSR-4 namespace used by the plugin. The former ran the risk of having same-named classes declared by multiple plugins with the site breaking. The latter ran the risk of having two or more plugins trying to use the same-named namespace, again breaking the site.

Joomla 4.0 added namespaces support for plugins. All we have to do is declare a namespace, a root folder for it under our plugin and make sure that the folder and file names follow the PSR-4 standard.

Your plugin's namespace prefix is declared in the XML manifest of the plugin using a new XML element under the <extension> root element:

<namespace path="src">My\Namespace\Prefix</namespace>

The path attribute tells Joomla which subdirectory of your extension holds the PSR-4 of your extension's PHP files. It is best practice to name it src but you don't have to. I always assume you are using src.

The text inside the XML element, My\Namespace\Prefix in our example, is the namespace prefix you will be using. Each plugin can register its own namespace prefix without any restrictions. It is recommended to use the convention MyCompany\Plugin\Folder\Name where MyCompany is the vendor namspace prefix, Folder is the plugin folder with its first letter capitalised (e.g. System for system plugins) and Name is the plugin's name with all of its letters lowercase except the first one which is capitalised (e.g. Example). Thus a plugin made by Acme Inc named example in the system folder would have the namespace Acme\Plugin\System\Example. Using this convention ensures that there will be no overlap in namespaces of different plugins since you cannot have two different plugins with the same name and plugin type.

Your plugin's class does not have to follow any specific naming convention or be placed in a specific sub-namespace of the plugin's namespace. This is determined in the plugin's Service Provider. It does have to extend from \Joomla\CMS\Plugin\CMSPlugin or one of its descendant classes.

It is customary to name it Extension, Plugin, or after the name of your plugin (e.g. Example) and place it in the Extension sub-namespace of your plugin. For example, our aforementioned example system plugin would customarily have its main plugin class be Acme\Plugin\System\Example\Extension\Example.

Any other classes you are shipping with and using in your plugin just follow the PSR-4 class naming standard.

The best part? Joomla registers namespaces when it boots. Even if your plugin is not yet loaded (but is enabled!) you have access to its classes using Joomla's PSR-4 autoloader. This is a typically much faster way to find out if a plugin is loaded or not instead of going through \Joomla\CMS\Plugin\PluginHelper::isEnabled. For example:

// The old way
$hasSystemExample = \Joomla\CMS\Plugin\PluginHelper::isEnabled('system', 'example');
// The new way
$hasSystemExample = class_exists(\Acme\Plugin\System\Example\Extension\Example::class, true);

This does NOT mean that you should stop using \Joomla\CMS\Plugin\PluginHelper::isEnabled though. There are plenty of cases where you know the type and name of a plugin but do not know how it has named its plugin class. In this case go through the slower, old way; it's safer than making arbitrary assumptions. Use the new way only for your own plugins since you are in full control of their classes's naming.