Plugins in Joomla

Plugins are the invisible workers of Joomla. They are event-driven code that runs in the background to change behaviour rather than to produce a page. A plugin has no URL, no module position, and often no visible output at all.

Yet plugins are how almost everything in Joomla gets extended without changing a single line of core code.

How Joomla reacts to events and extends itself without touching the core.

This article explains how Joomla plugins really work. It starts with the basics for website owners and administrators, then moves on to the technical details for developers. You will learn what a plugin is, how Joomla triggers it, how a modern plugin is built, and how to avoid the most common mistakes.

The one idea to take home is this: a plugin is a listener. It waits for something to happen, then reacts. Learn how one plugin subscribes to one event, and you understand how all of Joomla's extensibility works.

2. How Plugins Are Triggered

2.1 The Publish and Subscribe Model

Plugins work through Joomla's event dispatcher. There are two sides, and they never reference each other directly:

  PUBLISHER                            SUBSCRIBER
  (core or a component)                (your plugin)

  dispatch('onContentPrepare')  ---->  onContentPrepare()
        |                                    |
        |  "something happened"              |  "I'll handle it"
        └----------- decoupled ------------┘

• The publisher fires an event by name, then moves on.
• Every enabled plugin that subscribed to that name gets called, in order.
• Neither side knows about the other. This is called loose coupling.

This is the single most important pattern in Joomla. Once it clicks, the whole extension system starts to make sense.

2.2 An Event Has a Name, Data, and Sometimes a Result

When a component announces an event, it passes data along with it. A plugin can read that data, change it, or even stop the action:

// A component announces an event and passes data with it:
$event = new BeforeSaveEvent('onContentBeforeSave', [
    'context' => 'com_content.article',
    'subject' => $article,        // the data plugins may read / change
    'isNew'   => $isNew,
]);
$this->getDispatcher()->dispatch($event->getName(), $event);

// A plugin can stop the action:
if ($somethingWrong) {
    $event->addError('You shall not save.');
    $event->stopPropagation();     // no later plugin runs
}

An event typically carries these things:

2.3 The Naming Convention Reveals the Timing

Event names are deliberately readable. The verb inside the name tells you when it fires:

onContentBeforeSave   ← just before the action  (you can still cancel it)
onContentAfterSave    ← just after the action    (it already happened)
onUserLogin           ← the moment it occurs
onAfterRoute          ← a lifecycle checkpoint

4. Inside a Plugin (the Modern Structure)

4.1 The Joomla 4, 5 and 6 Folder Layout

Since Joomla 4, plugins are namespaced, PSR-4, dependency-injection-aware classes, just like components:

plugins/content/example/
├── example.xml                 ← manifest (group, element, files, params)
├── services/
│   └── provider.php            ← DI registration (the entry point)
├── src/
│   └── Extension/
│       └── Example.php         ← the plugin class (the listener)
├── language/                   ← translation .ini files
└── tmpl/ (optional)            ← layouts, if the plugin outputs HTML

Like components, the modern entry point is services/provider.php. There is no "magic" file-name loading anymore.

4.2 services/provider.php - Wiring the Plugin

The provider registers the plugin with the DI container and hands it any services it needs, such as the database or the application:

return new class () implements ServiceProviderInterface {
    public function register(Container $container): void
    {
        $container->set(
            PluginInterface::class,
            function (Container $container) {
                $dispatcher = $container->get(DispatcherInterface::class);
                $plugin = new Example(
                    $dispatcher,
                    (array) PluginHelper::getPlugin('content', 'example')
                );
                $plugin->setApplication(Factory::getApplication());
                return $plugin;
            }
        );
    }
};

The container injects the dependencies, so the plugin is testable and never reaches into global state.

4.3 The Plugin Class - Two Styles

Classic style (still supported): a public method per event, named after the event.

class Example extends CMSPlugin
{
    public function onContentPrepare($context, &$article, &$params, $page = 0)
    {
        $article->text = str_replace('{hello}', 'Hello JUG!', $article->text);
    }
}

Modern style (Joomla 5 and 6 preferred): implement SubscriberInterface and declare exactly which events you handle.

class Example extends CMSPlugin implements SubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return ['onContentPrepare' => 'transformText'];
    }

    public function transformText(ContentPrepareEvent $event): void
    {
        $article = $event->getItem();
        $article->text = str_replace('{hello}', 'Hello JUG!', $article->text);
    }
}

The method getSubscribedEvents() is explicit and fast. Joomla knows up front which events to route to you, instead of guessing from method names.

4.4 Reading and Writing Event Data

In the modern API you no longer use &$reference arguments. You use typed event objects with getters and setters:

public function transformText(ContentPrepareEvent $event): void
{
    $context = $event->getContext();   // 'com_content.article'
    $item    = $event->getItem();      // the article (object)
    $params  = $event->getParams();    // registry of params

    if ($context !== 'com_content.article') {
        return;                        // not for me - bail early
    }

    $item->text .= '<p>Added by my plugin.</p>';
}

Joomla 6 moves toward immutable events. Read with getters, change data through the methods the event provides, and abort with stopPropagation(). Do not mutate the arguments directly.

6. The Specialised Plugin Groups

6.1 Authentication and User - the Login Pipeline

Logging in is not one step but a small pipeline of events. Different plugin groups handle different stages:

Login form submitted
   v
onUserAuthenticate     ← authentication plugins each try to verify
   |   (Joomla DB? LDAP? OAuth? first success wins)
   v
onUserAuthorisation    ← is this verified user allowed in?
   v
onUserLogin / onUserAfterLogin   ← user plugins react (set session, log)

This is how single sign-on, social login, and 2FA all slot in without changing com_users.

6.2 Editors, Fields and Web Services

// A webservices plugin maps API routes to the component's API controllers:
public function onBeforeApiRoute(&$router)
{
    $router->createCRUDRoutes('v1/content/articles', 'articles', ['component' => 'com_content']);
}

Enabling Web Services - Content is literally just enabling a plugin. That is what switches on the endpoint /api/index.php/v1/content/articles.

6.3 Task Plugins - Joomla's Cron

The Scheduled Tasks component (com_scheduler) is powered entirely by task plugins:

A trigger (web cron / CLI / lazy) fires
   v
onExecuteScheduledTask
   v
The matching task plugin runs its job
   (delete old logs, rotate sessions, fetch a feed, send a digest ...)

• Each task plugin declares the routines it offers via getSubscribedEvents().
• This is the modern, GUI-managed replacement for hand-written cron jobs.

A task plugin is "just a plugin" that happens to be triggered by the scheduler instead of by a page view.

8. Beyond the Basics

8.1 Plugins Versus the Alternatives - Pick the Right Tool

Plugins are powerful, but they are not always the right choice. Use this table to decide:

If your answer is "whenever X happens, do Y", that is almost always a plugin.

8.2 Performance Considerations

Because system plugins run on every request, they are a prime tuning target:

A single badly written system plugin can slow down the entire site, because it runs on every page for every visitor.

8.3 Plugins and the Shared Services

Plugins are how Joomla's shared services stay decoupled and extensible:

• Custom Fields are delivered as fields plugins. Each field type is a plugin.
• Smart Search indexes content through finder plugins, one per content source.
• Categories fire content events too, such as onContentPrepare and onContentBeforeSave, with the context com_content.categories. So the same plugin can enhance articles and their categories.

if ($event->getContext() === 'com_content.categories') {
    // This same plugin also runs for category descriptions.
}

The shared category service is not a closed box. It emits the same events as articles, so plugins extend categories for free.

10. Best Practices

If you only remember a few things from this article, remember these:

• A plugin is an event listener. It changes behaviour, not the page.
• Subscribe to a single event, and always check the context before you act.
• Bail early to keep system plugins fast.
• Use getSubscribedEvents() and typed event objects in modern plugins.
• Mind the ordering when several plugins touch the same data.
• Pick the right tool: component for content, module for boxes, plugin for behaviour.

12. Summary

In Joomla, plugins are the quiet layer that ties everything together. They do not build pages and they do not sit in a position on the screen. Instead, they listen for events and react, which lets you extend almost any part of Joomla without changing core code.

Once you understand the publish-and-subscribe model, the rest follows naturally:

• System plugins hook the request lifecycle and run on every page.
• Content plugins wrap and transform content.
• Specialised groups cover authentication, users, editors, fields, web services, scheduled tasks, and two-factor login.
• Modern plugins are namespaced PSR-4 classes, wired by services/provider.php, using SubscriberInterface and typed events.

If you are planning a new feature, debugging unexpected behaviour, or wondering why a site is slow, plugins are often the place to look. They are small, but they shape how the whole system behaves.

If you need help building a custom plugin, tracking down a plugin that misbehaves, or making sure your event-driven code runs fast and safely, that is exactly the kind of advanced Joomla work I do every day.