Creating a plugin for Joomla

Writing a plugin for Joomla 5 involves several steps, from setting up the necessary files to implementing the plugin logic. Joomla plugins are event-driven and allow you to extend Joomla's functionality by listening for events triggered by the system or other extensions.

TL:DR – Here’s a detailed step-by-step guide on how to write a really simple Joomla 5 plugin. Out of acorns oak trees grow.

Step 1: Understand the Joomla Plugin Structure

Joomla plugins are stored in the /plugins/ directory. Each plugin is organized by type (e.g., content, system, etc.). Inside the plugin directory, you will have:

• XML manifest file: Defines plugin metadata and files to be installed.
• PHP file: Contains the plugin logic (main code).
• Optional files: Language files, helper files, or additional classes.

Step 2: Create the Plugin Directory Structure

You need to create a directory for your plugin under /plugins/[plugin_type]/[plugin_name].

For this example, we'll create a system plugin called helloworld.

Directory structure:

/plugins/system/helloworld/helloworld.php
/plugins/system/helloworld/helloworld.xml

Step 3: Create the XML Manifest File

The manifest file tells Joomla how to install your plugin and what resources it uses. Create helloworld.xml:

<?xml version="1.0" encoding="utf-8"?>
<extension type="plugin" group="system" method="upgrade" version="5.0">
    <name>plg_system_helloworld</name>
    <author>Your Name</author>
    <creationDate>2024-10-03</creationDate>
    <copyright>Your Company</copyright>
    <license>GPL</license>
    <version>1.0.0</version>
    <description>Helloworld Plugin for Joomla 5</description>

    <!-- Files included in the plugin -->

    <files>
        <filename plugin="helloworld">helloworld.php</filename>
    </files>

    <!-- Language file if needed -->
    <languages>
    <language tag="en-GB">en-GB.plg_system_helloworld.ini</language>
    </languages>

    <!-- Plugin metadata and settings -->
    <config>

     <fields name="params">

  <fieldset name="basic">
            <field name="message" type="text" label="Hello World Message" description="A message to display" default="Hello, Joomla 5!" />
        </fieldset>

</fields>
    </config>
</extension>

Key elements:

• <extension> tag defines the plugin type, group, and version.
• <files> tag lists the files needed by the plugin (e.g., helloworld.php).
• <config> defines configuration fields available in the plugin settings, such as a custom message.
• <fields name="params"> denotes that these fields are saved as plugin parameters in the extensions table in your Joomla database

Step 4: Write the Plugin Code (PHP File)

Now, create the main plugin file helloworld.php. This file contains the logic of your plugin

<?php
// No direct access

defined('_JEXEC') or die;

use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\CMS\Factory;

class PlgSystemHelloworld extends CMSPlugin
{
    protected $app;

    public function onAfterInitialise()
    {
    // Get the message from plugin parameters (config)
    $message = $this->params->get('message', 'Hello, Joomla 5!');

    // Output the message to the site (for demo purposes, we'll log it)
    Factory::getApplication()->enqueueMessage($message);
    }
}

Explanation:

• The PlgSystemHelloworld class extends CMSPlugin, which gives you access to Joomla’s event system.
• The onAfterInitialise() method is an event listener that triggers after Joomla’s initialization process. You can change this event depending on when you want your plugin to trigger (e.g., onContentPrepare, onBeforeRender).
• The plugin retrieves the message set in the plugin configuration ($this->params->get('message')) and logs it using enqueueMessage().

Step 5: (Optional) Add Language Files

If you want to add language support for your plugin, create a language file.

For example, create en-GB.plg_system_helloworld.ini inside a /language folder:

PLG_SYSTEM_HELLOWORLD="Helloworld Plugin"
PLG_SYSTEM_HELLOWORLD_MESSAGE_LABEL="Hello World Message"
PLG_SYSTEM_HELLOWORLD_MESSAGE_DESC="A message to display"

Step 6: Install the Plugin in Joomla

Once you have the plugin files ready, follow these steps to install it:

1. Zip the Plugin Files: Compress the /plugins/system/helloworld/ folder into a .zip file (make sure both helloworld.php and helloworld.xml are included).

2. Install via Joomla Admin:

   • Log into your Joomla 5 admin panel.
   • Go to Extensions > Manage > Install.
   • Upload your .zip file.

3. Enable the Plugin:

   • After installing, go to Extensions > Plugins.
   • Find the Helloworld plugin and enable it.

4. Configure the Plugin (if applicable):

   • Click on the plugin name, and you can configure any options defined in the XML manifest (e.g., change the message text).

Step 7: Test the Plugin

Once enabled, the plugin will run when Joomla triggers the event you’ve hooked into (onAfterInitialise in this case). If you’ve used enqueueMessage(), you should see the message on the front end or in the admin panel.

Events in Joomla 5 Plugins

Joomla plugins are event-driven. Here are some common events you can use in your plugin:

• onAfterInitialise: Triggered after the system is initialized.
• onBeforeRender: Triggered before rendering the page.
• onContentPrepare: Triggered when preparing content (useful for modifying content).
• onUserLogin: Triggered during user login.
• onAfterRoute: Triggered after routing is completed.

These events help you control when your plugin's logic is executed.

Summary

Creating a plugin for Joomla 5 involves:

• Setting up the correct file structure and defining the plugin metadata in the XML manifest.
• Writing the PHP logic to hook into Joomla’s event system.
• Optionally, adding language files for multi-language support.

This basic example shows how to output a message after initialization, but you can customize your plugin for more advanced features like form handling, payment integration, or content modification by hooking into Joomla’s event system.