Plugin Development: Scheduled Tasks

Previous Section: Extending Templates


If your plugin needs to perform a recurring task, you can set up a scheduled task to run on your chosen schedule for the plugin.

Contents

Why Use a Scheduled Task?

Scheduled tasks let you run a function on a recurring basis at an interval of your choice. Example cases where this is useful:

Registering a Scheduled Task

A task can be registered by using the Scheduled Task model's register method in the plugin's activate function. The first parameter is the name of the task, the second is a description that is shown on the scheduled tasks page and the third is the frequency in seconds. The frequency should be reduced by 15 seconds as this is the buffer we account for to ensure it does not add an extra minute when actually running. For example, you would enter 885 for every 15 minutes, or 3585 for every hour.


    public function activate()
    {
        try {
            // Add scheduled task
            \App\Modules\Core\Models\ScheduledTask::register(
                'My Task',
                'This is my task for My Plugin.',
                885
            );

            return true;
        } catch (\Exception $e) {
            return false;
        }
    }

When the plugin is now activated, it will add the scheduled task which will be visible when you visit Settings -> Core -> Scheduled Tasks.

Custom Scheduled Task

Remove Scheduled Task

A task can be removed by using the Scheduled Task model's deregister method in the plugin's deactivate and uninstall functions. It should be ran in both functions as the task must be removed if the plugin is no longer active or installed.


    public function deactivate()
    {
        try {
            // Remove scheduled task
            \App\Modules\Core\Models\ScheduledTask::deregister();

            return true;
        } catch (\Exception $e) {
            return false;
        }
    }

    public function uninstall()
    {
        try {
            // Remove scheduled task
            \App\Modules\Core\Models\ScheduledTask::deregister();

            return true;
        } catch (\Exception $e) {
            return false;
        }
    }

Running Scheduled Task

The scheduled task is now set up and scheduled to run on the interval you've set, but you still need to code what it should do. The plugin controller must implement ScheduledTaskInterface and then define a runTask function which is what is ran each time the scheduled task runs, like below.

Controllers/HelloWorld.php

    <?php

    namespace App\Plugins\HelloWorld\Controllers;

    use App\Modules\Core\Controllers\Plugins\Plugin;
    use App\Modules\Core\Interfaces\ScheduledTaskInterface;

    class HelloWorld extends Plugin implements ScheduledTaskInterface
    {

        ...

        public function runTask()
        {
            // Run our task code
        }
    }

The function doesn't need a return statement, but it should throw an exception with a message is there is an error, this will log the error in application log files.


Next Section: Sending Emails