It might come to you as a surprise, but the original way plugins were implemented in Joomla 1.0 back in 2005 is still supported in Joomla 4. This support will be removed in Joomla 6, scheduled for release in 2025, two decades after it first appeared. Sure, there have been refinements but the core concept still applies.

Legacy plugins consist of a single class which is named PlgTypeName where Type is the plugin type a.k.a. folder (e.g. system, user, console, …) and Name is the name of the plugin. For example, we could have PlgSystemExample for a system plugin named example and which lives in plugins/system/example/example.php. The class always extends from \Joomla\CMS\Plugin\CMSPlugin or one of its sub-classes typically defined in a component (e.g. finder plugins extend from \Joomla\Component\Finder\Administrator\Indexer\Adapter which extends from \Joomla\CMS\Plugin\CMSPlugin).

Any public method whose name starts with on is registered as an event listener. Therefore a method called onFooBar is registered as a legacy plugin event listener for an event called onFooBar.

There's a small caveat when it comes to Joomla 4 and 5. If the method accepts only one parameter which is either named $event OR is type-hinted as a class implementing \Joomla\Event\EventInterface then the method is registered as an event listener, a new type of listener. See Legacy vs Event Listener methods. This is a deliberate design choice which lets you write plugins which can simultaneously handle legacy events when running under Joomla 3 and modern events when running under Joomla 4 and 5. This lets you provide a version of your plugin which acts as a “bridge” for people migrating from Joomla 3 to 4 and 5: the same plugin can run on both versions of Joomla without breaking the site.

As noted earlier, Joomla 4 introduced Dependency Injection and service providers for all extensions, of course including plugins. It should come as no surprise then that the second plugin variant we get is similar to the legacy plugins but with namespaces and service providers.

The first difference you will notice is that the XML manifest goes from this:

<?xml version="1.0" encoding="utf-8"?>
<extension type="plugin" group="system" method="upgrade">
    <name>plg_system_example</name>
    <author>D.Veloper</author>
    <creationDate>2022-10</creationDate>
    <copyright>(C) 2022 Acme Inc</copyright>
    <license>GNU General Public License version 2 or later; see LICENSE.txt</license>
    <authorEmail>d.veloper@acme.com</authorEmail>
    <authorUrl>www.acme.com</authorUrl>
    <version>1.0.0</version>
    <description>PLG_SYSTEM_EXAMPLE_XML_DESCRIPTION</description>
    <files>
        <filename plugin="example">example.php</filename>
    </files>
    <languages>
        <language tag="en-GB">language/en-GB/plg_system_example.ini</language>
        <language tag="en-GB">language/en-GB/plg_system_example.sys.ini</language>
    </languages>
</extension>
            

to this:

<?xml version="1.0" encoding="utf-8"?>
<extension type="plugin" group="system" method="upgrade">
    <name>plg_system_example</name>
    <author>D.Veloper</author>
    <creationDate>2022-10</creationDate>
    <copyright>(C) 2022 Acme Inc</copyright>
    <license>GNU General Public License version 2 or later; see LICENSE.txt</license>
    <authorEmail>d.veloper@acme.com</authorEmail>
    <authorUrl>www.acme.com</authorUrl>
    <version>1.0.0</version>
    <description>PLG_SYSTEM_EXAMPLE_XML_DESCRIPTION</description>
    <namespace path="src">Acme\Plugin\System\Example</namespace>
    <files>
        <folder>services</folder>
        <folder plugin="example">src</folder>
    </files>
    <languages>
        <language tag="en-GB">language/en-GB/plg_system_example.ini</language>
        <language tag="en-GB">language/en-GB/plg_system_example.sys.ini</language>
    </languages>
</extension>
            

The affected lines are in bold type.

First of all, we have a <namespace> tag to declare our namespace. The namespace follows the convention MyCompany\Plugin\Type\Name where MyCompany is the vendor namespace prefix, Type is the plugin type a.k.a. folder (e.g. system, user, console, …) and Name is the name of the plugin. TheType must be written as Uppercasefirst i.e. the first letter is uppercase and all others are lowercase.

The second obvious change is that instead of a plugin file we have two folders, services and src.

The services folder contains a single file, provider.php. It's very similar to a component's service provider file:

<?php
defined('_JEXEC') || die;

use Joomla\CMS\Extension\PluginInterface;
use Joomla\CMS\Factory;
use Joomla\CMS\Plugin\PluginHelper;
use Joomla\DI\Container;
use Joomla\DI\ServiceProviderInterface;
use Joomla\Event\DispatcherInterface;
use Acme\Plugin\System\Example\Extension\Example;

return new class implements ServiceProviderInterface {
    public function register(Container $container)
    {
        $container->set(
            PluginInterface::class,
            function (Container $container)
            {
                $config  = (array)PluginHelper::getPlugin('system', 'example');
                $subject = $container->get(DispatcherInterface::class);

                $app = Factory::getApplication();

                /** @var \Joomla\CMS\Plugin\CMSPlugin $plugin */
                $plugin = new Example($subject, $config);
                $plugin->setApplication($app);

                return $plugin;
            }
        );
    }
};

The important thing to note here is that the service provider is responsible for registering a Joomla\CMS\Extension\PluginInterface service which returns an object instance of our plugin class.

The plugin class, as with legacy plugins, extends from \Joomla\CMS\Plugin\CMSPlugin and works the same as a Legacy plugin's class.

You will not see any plugins of this type in the core and they are pretty rare in the wild, mostly from software — like older versions of mine — which started the conversion process to Joomla 4 before Joomla 4 was finished and before the modern event system was mature enough for general use.

Practically speaking, the only use case for this type of plugin is if you still have plugin events which pass around scalar variables by reference. For example, something like this:

public function onMyCustomEvent(string $foo, array &$bar);

The $bar variable is a scalar (array) passed by reference. It can be modified by the plugin event handler. This will not be possible using modern events.

If you want a clean solution you need to make changes in the code which calls this plugin event. Instead of passing around an array you'd have to pass a \Joomla\CMS\Object\CMSObject or \Joomla\Registry\Registry object created from the contents of the array. Your modern event handler can modify that object (objects are always passed by reference in all versions of PHP supported by Joomla 4 and beyond). Then your consumer code could convert back from an object to an array.

The clean solution is admittedly more convoluted than you might expect and requires changes in the consumer which might not be possible if it's not code under your control. If you do not feel confident implementing the cleaner solution, or if it's just not possible because third party code is using your events, you can create a Joomla 4 classic plugin with a legacy plugin event handler for your plugin event which won't give you a hard time with scalar variables passed by reference. It's not the best coding practice but it does take a while —and several refactoring passes— to migrate to a cleaner architecture. Even more so considering that Joomla 3 and these coding practice had been around for nearly a decade before Joomla 4 was released.

You might remember from an earlier chapter talking about the basic services in a component's service provider that you can trigger plugins using modern events like so:

$event = new \Joomla\Event\Event('onSomething', [$param1, $param2]);
$this->getDispatcher()->dispatch($event->getName(), $event);
$results = $event->getArgument('result', []);

It follows reason that Joomla 4 offers a way to write plugins which only deal with these modern events. These events are faster and have many more tricks up their sleeves than the ‘dumb’ callback model implemented in Joomla 1.x, 2.x and 3.x.

Plugins of this type are just like Joomla 4 classic plugins with a twist. The plugin class implements the \Joomla\Event\SubscriberInterface. This changes the way Joomla registers event handlers. Implementing this interface requires you to implement the getSubscribedEvents method, defined in the interface. This returns an array mapping event names to the names of public methods of your plugin.

The implementation of the getSubscribedEvents method is pretty straightforward:

public static function getSubscribedEvents(): array
{
    return [
        'onSomething'     => 'doSomething',
        'onSomethingElse' => ['doSomething', \Joomla\Event\Priority::HIGH],
    ];
}

The keys of the array are the event names. The values are the names of the methods which handle each event.

But, wait a minute! That second item has an array value. What is that? Well, that's one of the benefits of using SubscriberInterface: you can tell Joomla about the priority you want for your event handler, meaning that the order plugins execute is not dictated only by their user-defined ordering in the backend of the site but also by the programmer's preferred priority.

By default, all event handlers are attached with Normal priority. They are then executed in the order they were attached, i.e. how the plugins were ordered in the backend Plugins management page of the site. This is the only option you get with legacy and classic plugins.

Plugins implementing the SubscriberInterface can optionally set a priority for each event handler. This is an integer. The higher the integer is, the earlier your event handler executes. Joomla first executes all event handlers with the highest priority number in the order they were attached. Then moves to the event handlers with the second highest priority number in the order they were attached and so on.

If you set your priority to high, as I did above, your event handler will be one of the first (if not the absolute first) to be executed. If, conversely, you set it to \Joomla\Event\Priority::MIN or even PHP_INT_MIN your event handler will be one of the last (if not the absolute last) to be executed. In the few cases where this is truly needed you no longer have to tell your users to reorder plugins for your plugin to work correctly and predictably; you can just set the priority.

Moreover, you should keep in mind that all methods handling events only accept one argument (by value, not reference!), an event object which implements the \Joomla\Event\EventInterface interface. We will talk about this in the next section on listener types.

Why bother? Performance!

When you are using SubscriberInterface in your plugins you can and should set the protected property $this->allowLegacyListeners = false; to tell Joomla! that your plugin only handles plugin events defined by the getSubscribedEvents method. Joomla will NOT use the super slow PHP ReflectionObject to find public methods whose name starts with on. It will instead only call the public static method getSubscribedEvents which is defined in the interface and implemented in your plugin class and register the event handlers it describes.

This is the key to massive performance improvement on your users' sites.

Not having to go through reflection saves a lot of time on every page load of the site. Moreover, events are self-contained objects being passed around which reduces the overhead of calling each event handler. These add up with the dozens to hundreds of plugins and event handlers running on a typical Joomla site, saving several dozens to a few hundreds of milliseconds of page load time. This is a significant performance improvement for the site. This is why I've been telling people since 2017, that modern events make Joomla 4 and later versions faster.

As we have already alluded to in the previous sections, there are two types of plugin event listeners.

Legacy plugin event listeners

Legacy plugin event listeners are nothing more than glorified callbacks. They are plain old methods which accept a number of parameters and possibly^[10] return a value. For example, we could have something like this:

public onSomething(string $foo, array $bar): array

This simplicity is simultaneously the strength and the Achille's heel of legacy plugin event handlers.

The only thing this simple callback arrangement has going for it is that, well, it's very simple to implement in the code which calls the plugin events, the core code which runs the plugin event handlers and the code which consumes the results of plugin event handlers — though the latter is debatable.

Modern event listeners

Joomla 4 introduced a whole new concepts: events.

Each event is its own object. It has arguments which can be anonymous or named, typically the former in generic events and the latter in concrete events. Events always have a named argument called result which lets the event handler not only return a result but also inspect what other results were returned by event handlers called before it (most concrete events have an addResult method to facilitate returning results). A concrete event class can implement type checks and validation of any (or all) of its arguments, including the results. It's no longer the Wild West.

Event handlers have the option to stop the processing of an event's handlers by calling the event object's stopPropagation method; this is useful when you want to run a number of plugins until you get at least one result. Think about avatars displayed in a forum. You may have a number of plugins which can return an avatar image: Gravatar (if the user has an account there), using an image source from a user field, Facebook (if the user has linked an account), a locally installed social network component, and a fall-back to a generated fake avatar. The first avatar found will be used, the rest will be discarded. If the rest are going to be discarded, why even bother running the code to check if they exist?! Instead, each avatar plugin would work like this. It runs its code. If there is no avatar to be reported, return. If there is an avatar to be reported use addResult to return it and call the event's stopPropagation method to prevent the other avatar plugins from running for no reason and wasting the user's time and your server's resources. This is something you just cannot do with legacy event listeners.

Also, as we mentioned earlier, modern event handlers can have prioritised event handlers with all the benefits we already mentioned.

Modern event handlers are fairly simple:

public function handleSomething(\Joomla\Event\Event $event): void

Note the type-hint to the $event argument. As written above, the method can be used to handle any event. In most cases you will need to use a concrete event class: either the concrete core event classes supplied in Joomla's libraries/src/Event directory and its subdirectories or a concrete event class provided by another Joomla extension.

Getting the arguments to the event depends on the event class itself. For generic events you'd need to do something like:

[$param1, $param2, $param3] = $event->getArguments();

That's because generic events do not have named arguments. This is the equivalent of having a legacy plugin event handler with the method signature:

public function onSomething($param1, $param2, $param3);

With concrete events, it depends on the event. In most cases you'd do either of the following:

// Named arguments without a getter method
$param1 = $event->getArgument('param1');
// Named arguments with getter methods
$param2 = $event->getParam1();

Any decent IDE will let you know if there is a getter in $event based on its type-hint. That's why it makes sense to type-hint your event handler methods correctly.

The return type of a modern event handler is always void. You do NOT return values directly. Instead, you add them to the result argument which is always an array:

$result = $this->getArgument('result') ?? [];
$result[] = $theResultIAmReturning;
$this->setArgument('result', $result);

Most concrete event classes implement the \Joomla\CMS\Event\Result\ResultAwareInterface which has the addResult method to return values more easily:

$this->addResult($theResultIAmReturning);

Finally, remember that events can be mutable, immutable or selectively immutable. A mutable event allows its handlers to use setArgument freely, modifying all of its arguments.

An immutable event does not allow any of its arguments to be set after it has been created. This does not mean that you cannot do anything with the arguments! Remember that argument values which are objects can be modified without needing to set the argument again. For example, this is a valid, working event handler:

	public function handleTableAfterLoad(\Joomla\CMS\Event\Table\AfterLoadEvent $event): void
{
    if (!$event->getArgument('result')) return;

    /** @var \Joomla\CMS\Table\TableInterface $table */
    $table = $event->getArgument('subject');

    $table->modified_by = \Joomla\CMS\Factory::getApplication()
        ->getIdentity()
        ->id;
}

The \Joomla\CMS\Event\Table\AfterLoadEvent concrete event class is an immutable event. However, it has a subject argument which contains a Joomla Table object. All objects in PHP are passed by reference; any change we make to it will persist when we return from our method. That's why we can change its modified_by property without returning any value from our event handler and despite the event itself being immutable.

Finally, we have selective immutable events. On the face of it, they are immutable events. However, they have setter methods for specific named arguments. Actually, the \Joomla\CMS\Event\Table\AfterLoadEvent is a selectively immutable event. It has setters for the result and row arguments. Every event implementing \Joomla\CMS\Event\Result\ResultAwareInterface is selectively immutable; there is always the addResult method to add to the results returned by the event.

Handling events is a bit more involved than using simple callback methods like you used to in legacy plugins. If you feel utterly lost, var_dump the $event variable and die();^[11]. You will get a lot of insight as to what the event does and which data does it carry.