How to Create Joomla Task Scheduler Plugin

Joomla! included Task Scheduler from the version Joomla! 4.1. It helps to automate repetitive and routine tasks for for a wide variety of maintenance and reporting tasks.

The task scheduler runs the task defined in the Plugin via a cron job.

Cron Job: A cron job is used to automate repetitive tasks. For example, to process email queues, to synchronise e-commerce orders, to check website for issues and so on.

Task Scheduler Plugin

It is a standard Joomla! plugin with group="task". You have to use TaskPluginTrait.

use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\Component\Scheduler\Administrator\Event\ExecuteTaskEvent;
use Joomla\Component\Scheduler\Administrator\Task\Status;
use Joomla\Component\Scheduler\Administrator\Task\Task;
use Joomla\Component\Scheduler\Administrator\Traits\TaskPluginTrait;
use Joomla\Event\SubscriberInterface;

class PlgTaskExample extends CMSPlugin implements SubscriberInterface
{
    use TaskPluginTrait;
    
    protected const TASKS_MAP = array(
        'plg_task_do_example' => array(
            'langConstPrefix' => 'PLG_TASK_DO_EXAMPLE',
            'method' => 'doExample',
            'form' => 'do_example'
            )
        );

    protected $autoloadLanguage = true;
    protected $app;
    protected $db;
    
    public static function getSubscribedEvents(): array
    {
        return array(
            'onTaskOptionsList' => 'advertiseRoutines',
            'onExecuteTask' => 'standardRoutineHandler',
            'onContentPrepareForm' => 'enhanceTaskItemForm',
        );
    }
    
    private function doExample(ExecuteTaskEvent $event): int
    {
        // Code for Tasks
        
        return Status::OK;
    }
}

Implementation

A task plugin needs to include TaskPluginTrait and define methods corresponding to each routine along with the TASKS_MAP class constant to declare supported routines and related properties. This trait includes standard methods to broadcast routines, enhance task forms and call routines.

advertiseRoutines()

This method advertises the task routines supported by the plugin. This method should be mapped to the onTaskOptionsList event, enabling the plugin to advertise its routines. This method is already defined in the trait, so you are not required to define it in your plugin.

enhanceTaskItemForm()

This method enhances the task form from an XML file declared through the TASKS_MAP constant. This method can be mapped to the onContentPrepareForm event. This method is already defined in the trait, so you are not required to define it in your plugin.

You need to add the form name in the TASKS_MAP and constant and create XML form in the forms folder of the plugin with the same name.

standardRoutineHandler()

Standard routines are mapped to valid class methods. You can add the method name in the TASKS_MAP constant and define it in your plugin. This is the method that will executed when task is run.

This method should be mapped to the onExecuteTask event. These methods are expected to take a single argument (the Event) and return an status integer.

logTask()

This method add a log message to the task log. The first argument is the message and the second argument is the priority. The log message priority can be dubug, error, warning, notice, info.

$this->logTask('Task is being executed', 'info');

Task Exit Status

There are 12 exit status for tasks which are mapped to integer values.

  1. INVALID_EXIT = -2: Used when a routine returns an invalid (non-integer) exit code.
  2. NO_EXIT = -1: Used when a routine does not return an exit code.
  3. RUNNING = 1: Used when the routine just starts. This is not meant to be an exit code.
  4. NO_LOCK = 2: Used on failure to acquire a pseudo-lock.
  5. NO_RUN = 3: Used on failure to run the task.
  6. NO_RELEASE = 4: Used on failure to release lock or update the record.
  7. KNOCKOUT = 5: Used when a routine is either "knocked out" by an exception.
  8. WILL_RESUME = 123: Used when a task needs to resume. Use this for long running tasks to split them into smaller batches. When the last batch is executed return Status::OK.
  9. TIMEOUT = 124: Used when a task times out.
  10. NO_TASK = 125: Used when a task does not exist.
  11. NO_ROUTINE = 127: Used when a routine is missing.
  12. OK = 0: This is the exit code on success.