scheduled-tasks.md

category
Develop

Scheduled tasks

Scheduled tasks let you execute tasks regularly (hourly, weekly, …), for example:

• create and send custom reports or summaries
• sync users and websites with other systems
• clear any caches

Adding a scheduled task to your plugin

You can add a scheduled task to your plugin by using the console:

$ ./console generate:scheduledtask

The command will ask you to enter the name of your plugin and will create a plugins/MyPlugin/Tasks.php file. This file contains some examples to get you started:

class Tasks extends \Piwik\Plugin\Tasks
{
    public function schedule()
    {
        $this->hourly('myTask');  // myTask() will be executed once every hour
        $this->daily('myTask');   // myTask() will be executed once every day
        $this->weekly('myTask');  // myTask() will be executed once every week
        $this->monthly('myTask'); // myTask() will be executed once every month

        // pass a parameter to the task
        $this->weekly('myTaskWithParam', 'anystring');

        // specify a different priority
        $this->monthly('myTask', null, self::LOWEST_PRIORITY);
        $this->monthly('myTaskWithParam', 'anystring', self::HIGH_PRIORITY);
    }

    public function myTask()
    {
        // do something
    }

    public function myTaskWithParam($param)
    {
        // do something
    }
}

Simple example

As you can see in the generated template you can execute tasks hourly, daily, weekly and monthly by registering a method which represents the actual task:

public function schedule()
{
    // register method remindMeToLogIn to be executed once every day
    $this->daily('remindMeToLogIn');
}

public function remindMeToLogIn()
{
    $mail = new \Piwik\Mail();
    $mail->addTo('[email protected]');
    $mail->setSubject('Check stats');
    $mail->setBodyText('Log into your Piwik instance and check your stats!');
    $mail->send();
}

This example sends you an email once a day to remind you to log into your Piwik daily. The Piwik platform makes sure to execute the method remindMeToLogIn exactly once every day.

Passing a parameter to a task

Sometimes you want to pass a parameter to a task method. This is useful if you want to register for instance one task for each user or for each website. You can achieve this by specifying a second parameter when registering the method to execute.

public function schedule()
{
    foreach (\Piwik\Site::getSites() as $site) {
        // create one task for each site and pass the URL of each site to the task
        $this->hourly('pingSite', $site['main_url']);
    }
}

public function pingSite($siteMainUrl)
{
    file_get_contents($siteMainUrl);
}

Testing scheduled tasks

To manually execute all scheduled tasks, you can run the following command:

$ ./console core:run-scheduled-tasks --token-auth=YOUR_TOKEN_AUTH

There is one problem with this though: Piwik makes sure the scheduled tasks are executed only once an hour, a day, etc. This means you can't simply run the command again and again as you would have to wait for the next hour or day.

To solve this, the --force option will force to execute all tasks, even those that are not due to run at this time.

$ ./console core:run-scheduled-tasks --force --token-auth=YOUR_TOKEN_AUTH

Remember that manually testing your scheduled task is just the first step: adding unit or integration tests is the best way to avoid regressions.

Which tasks are registered and when is the next execution time of my task?

The TasksTimetable plugin from the Marketplace can answer this question for you. Simply install and activate the plugin with one click by going to Settings > Marketplace > Get new functionality. It will add a new admin menu item under Settings named Scheduled Tasks.

Read more

You can read more about scheduled tasks in the Tasks class reference.