Creating a Plugin for Joomla from Scratch
Learn the foundations of Joomla plugin development, from event-driven architecture and manifest files to namespacing, installation, testing, security, and maintenance.
Joomla plugin development is a practical way to add focused behavior to a site without changing Joomla core. A plugin listens for an event, runs its own code when that event occurs, and can sometimes return or modify a result for the calling extension.
This article explains the architecture behind a small plugin and gives you a sensible development path. You will see how plugin groups, manifest files, namespaces, service providers, event subscribers, language files, installation, and troubleshooting fit together. The examples follow the modern Joomla 4 and 5 style described in the supplied developer material, so check the documentation for your installed Joomla version before releasing code.
What a Joomla plugin does
A Joomla plugin is an extension connected to one or more trigger events. Joomla core provides events, and other extensions can also dispatch custom events. When a matching event fires, Joomla calls the subscribed plugin methods in sequence.
That makes a plugin a good fit for behavior such as:
- Preparing article text before it is displayed
- Adding information after an article title
- Responding to authentication or user events
- Integrating a site with another service
- Adding a narrowly scoped content or system action
Plugins are different from components, modules, and templates. A component usually owns a larger application area, a module displays a block of output, and a template controls presentation. A plugin is usually event-driven and works behind the scenes.
A useful mental model is the observer pattern. Joomla dispatches an event, and registered listeners observe it. In current Joomla architecture, the event dispatcher and dependency injection container help connect your plugin to that process.
Plan the plugin before writing PHP
Start with one event and one clearly defined result. For example, a content plugin might replace a deliberately chosen token in an article, or add a short notice after a title. Avoid beginning with a collection of unrelated features. A small first plugin is easier to test and less likely to affect every page on a site.
Write down these decisions first:
- Plugin group: Choose the event family, such as
contentorsystem. - Element name: Select a short, stable name used by the manifest, folder, and lookup code.
- Events: Identify the exact events the plugin will subscribe to.
- Client scope: Decide whether it should run on the site, administrator area, API, or more than one client.
- Output or side effect: Define what changes and when it should not run.
For a first local test site, install Joomla locally before you develop against a production installation. A disposable site makes it safer to enable, disable, reinstall, and debug the extension.

Build the Joomla plugin manifest
The XML manifest tells Joomla what the extension is and which files it should install. A minimal modern content plugin needs an extension declaration, a namespace, the plugin entry point, source files, and language file paths.
A simplified structure looks like this:
<?xml version="1.0" encoding="utf-8"?>
<extension method="upgrade" type="plugin" group="content">
<name>PLG_CONTENT_EXAMPLE</name>
<version>1.0.0</version>
<description>PLG_CONTENT_EXAMPLE_DESCRIPTION</description>
<namespace path="src">Example\Plugin\Content\Example</namespace>
<files>
<folder plugin="example">services</folder>
<folder>src</folder>
</files>
<languages>
<language tag="en-GB">language/en-GB/plg_content_example.ini</language>
<language tag="en-GB">language/en-GB/plg_content_example.sys.ini</language>
</languages>
</extension>The type identifies the extension as a plugin. The group identifies the plugin group, not another extension type. The plugin value on the services folder is the element name Joomla uses when it discovers the entry point.
Keep these values consistent:
- The XML filename should match the plugin element, such as
example.xml. - The namespace in the manifest should match the PHP namespace and the import in the service provider.
- The group and element used in plugin lookup should match the manifest.
- Language filenames should contain the plugin group and element.
Small naming mismatches can allow an installation to appear successful while preventing Joomla from loading the class you expect.
Organize the plugin files
A practical plugin package might look like this:
plg_example/
├── example.xml
├── services/
│ └── provider.php
├── src/
│ └── Extension/
│ └── Example.php
└── language/
└── en-GB/
├── plg_content_example.ini
└── plg_content_example.sys.iniThe exact class names can differ, but the structure must agree with the manifest. In particular, the namespace path points to the source tree, while the provider connects the Joomla service container to the plugin class.
If you are new to the wider extension model, the Joomla extension guide provides useful context on how plugins compare with components, modules, and templates.
Register the service provider
The service provider is the bridge between Joomla's dependency injection container and your plugin class. The surrounding code is mostly standard, but three values need careful attention: the imported extension class, the plugin group and element passed to the helper, and the class that is instantiated.
The central pattern is:
use Joomla\CMS\Extension\PluginInterface;
use Joomla\CMS\Plugin\PluginHelper;
use Joomla\DI\Container;
use Joomla\DI\ServiceProviderInterface;
use Joomla\Event\DispatcherInterface;
use Example\Plugin\Content\Example\Extension\Example;
return new class implements ServiceProviderInterface
{
public function register(Container $container)
{
$container->set(
PluginInterface::class,
function (Container $container) {
$config = (array) PluginHelper::getPlugin('content', 'example');
$subject = $container->get(DispatcherInterface::class);
$plugin = new Example($subject, $config);
return $plugin;
}
);
}
};The namespace in use Example\Plugin\Content\Example\Extension\Example must agree with the manifest and the class declaration. Likewise, getPlugin('content', 'example') must use your actual group and element. Treat these names as a connected set rather than independent labels.
Subscribe to events in the extension class
The extension class contains the behavior. A modern plugin can implement SubscriberInterface and return an event-to-method map. The following example shows the shape without attempting to implement a complete content transformation:
namespace Example\Plugin\Content\Example\Extension;
use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\Event\Event;
use Joomla\Event\SubscriberInterface;
final class Example extends CMSPlugin implements SubscriberInterface
{
public static function getSubscribedEvents(): array
{
return [
'onContentPrepare' => 'prepareContent',
];
}
public function prepareContent(Event $event): void
{
if (!$this->getApplication()->isClient('site')) {
return;
}
[$context, $article, $params, $page] = array_values(
$event->getArguments()
);
if ($context !== 'com_content.article') {
return;
}
// Apply one narrowly defined content change here.
}
}Your handler should check the client and context before changing data. It should also handle the event arguments according to the Joomla version you support. The supplied Joomla programmer example notes that generic and concrete events can expose their arguments through the event object, while result handling may differ. Test the event behavior on the target versions instead of assuming that every event returns data in the same way.
A plugin that changes article text should preserve valid markup, avoid repeatedly transforming the same content, and leave unrelated contexts alone. If the plugin only needs to observe an action, do not modify the event or article unnecessarily.
Add language files and configuration
Use language constants for the manifest name, description, administrator messages, and user-facing output. For example:
PLG_CONTENT_EXAMPLE="Example Content Plugin"
PLG_CONTENT_EXAMPLE_DESCRIPTION="Adds the example content behavior"
PLG_CONTENT_EXAMPLE_NO_MATCH="The requested value was not found"The system language file supplies strings used while Joomla lists the extension. The regular language file supplies strings used by the plugin at runtime. Load the language strings before calling them, or configure the plugin to autoload its language resources.
If the plugin needs settings, define them through the plugin configuration form rather than hard-coding site-specific values. Keep defaults safe, document what each option changes, and validate values before using them in output or queries.
Install, enable, and test the plugin
Package the plugin directory as a ZIP file with the manifest at the expected level. In the Joomla administrator area:
- Open the extension installation screen.
- Upload the plugin ZIP package.
- Confirm that Joomla reports a successful installation.
- Open the Plugins manager.
- Find the plugin by its language-defined name.
- Enable it and configure its options.
- Trigger the event in a controlled test article or page.
Installation alone does not make a plugin run. The plugin must be enabled, the event must actually fire, and the handler must accept the arguments supplied by that event.
Test both the expected path and the boundaries around it:
- An article that should trigger the plugin
- An article with no matching token or condition
- Administrator and site requests
- Featured content if it is supported
- Empty or unexpected input
- Repeated saves and page loads
- A disabled plugin and an uninstall or upgrade
Keep browser developer tools, Joomla logs, and PHP error reporting available on the local site. Do not turn verbose errors on for visitors to a production site.
Common Joomla plugin development problems
The plugin installs but does not appear
Check the manifest type, group, element, filename, and language paths. Confirm that the ZIP does not add an unexpected outer directory that changes the package layout.
The plugin appears but never runs
Make sure it is enabled and that the selected event is fired in the page or action you are testing. A client check can also exclude the current request. Log a safe, temporary marker during local testing to confirm that Joomla reaches the handler.
Joomla cannot find the class
Compare the manifest namespace, the namespace declaration in the PHP class, the use statement in provider.php, and the source folder. Namespace changes may also require a fresh installation so Joomla can rebuild its autoload mapping.
The plugin changes the wrong pages
Narrow the context check and client check. A content event can be used in more places than the one page you had in mind, so treat every handler as code that may affect many requests.
The output is unsafe or malformed
Escape values for their output context, validate configuration, and avoid inserting raw user input into HTML, attributes, queries, or scripts. Use Joomla APIs and prepared database operations instead of assembling unsafe queries by hand.
Security and maintenance practices
A plugin executes inside the Joomla application, so a small mistake can have a wide effect. Use the least access and least scope needed for the feature. Do not rely on hidden administrator URLs as protection. Check permissions where the action requires authorization, and verify tokens for state-changing requests.
Also consider the maintenance path before release:
- State the Joomla and PHP versions you support.
- Avoid relying on deprecated APIs when a supported service exists.
- Keep the package version visible in the manifest.
- Make upgrades repeatable with
method="upgrade"and predictable files. - Remove temporary logging and test shortcuts.
- Test after Joomla, PHP, template, and related extension updates.
- Document the event, configuration, and expected behavior for the site owner.
For broader development context, the Joomla developer documentation can help you continue from a small plugin into a complete extension workflow. The supplied research also warns that some older tutorial pages are archived, so always compare examples with the documentation version for the Joomla installation you support.
Frequently Asked Questions
What is the difference between a Joomla plugin and a component?
A plugin responds to events raised by Joomla or another extension. A component usually owns a larger feature area with its own routes, views, and administrator or site workflow. Choose a plugin for a focused event-driven behavior and a component for a substantial application feature.
Do I need to enable a Joomla plugin after installing it?
Yes. Installation copies and registers the extension, but the plugin normally must also be enabled in the Joomla Plugins manager. It will not respond to events while disabled.
Which files are essential in a Joomla plugin?
A modern plugin package commonly includes an XML manifest, a services/provider.php file, a namespaced class under src, and language files. The exact contents depend on the plugin group, configuration, and Joomla version.
How should I test a new Joomla plugin?
Use a local or staging Joomla site. Test the normal event, excluded contexts, empty input, repeated execution, disabled state, upgrade, and uninstall. Review logs and PHP errors without exposing verbose diagnostics to public visitors.
Conclusion
Creating a plugin for Joomla becomes manageable when you treat the manifest, namespace, service provider, event subscription, and language files as one connected system. Start with one event and one safe behavior, test it on a local site, narrow its scope, and verify it against the Joomla version you plan to support. That workflow gives you a dependable foundation for broader Joomla plugin development and extension work.