Task Scheduling

#Introduction

In the past, developers have generated a Cron entry for each task they need to schedule. However, this can sometimes be a headache. Your task schedule is no longer in source control, and you must SSH into your server to add the Cron entries. The command scheduler allows you to fluently and expressively define your command schedule within the application itself, and only a single Cron entry is needed on your server.

NOTE: See the installation guide for instructions on how to set up the scheduler task.

#Defining schedules

You may define all of your scheduled tasks by overriding the registerSchedule method inside the Plugin registration class. The method will take a single $schedule argument and is used for defining commands along with their frequency.

To get started, let's look at an example of scheduling a task. In this example, we will schedule a Closure to be called every day at midnight. Within the Closure we will execute a database query to clear a table:

class Plugin extends PluginBase
{
    [...]

    public function registerSchedule($schedule)
    {
        $schedule->call(function () {
            \Db::table('recent_users')->delete();
        })->daily();
    }
}

In addition to scheduling Closure calls, you may also schedule console commands and operating system commands. For example, you may use the command method to schedule a console command:

$schedule->command('cache:clear')->daily();

The exec command may be used to issue a command to the operating system:

$schedule->exec('node /home/acme/script.js')->daily();

#Schedule frequency options

Of course, there are a variety of schedules you may assign to your task:

These methods may be combined with additional constraints to create even more finely tuned schedules that only run on certain days of the week. For example, to schedule a command to run weekly on Monday:

$schedule->call(function () {
    // Runs once a week on Monday at 13:00...
})->weekly()->mondays()->at('13:00');

Below is a list of the additional schedule constraints:

Timezones

Using the timezone method, you may specify that a scheduled task's time should be interpreted within a given timezone:

$schedule->call(function () {
    // Runs every day at 13:00 Paris time...
})->timezone('Europe/Paris')->at('13:00');

If you are repeatedly assigning the same timezone to all of your scheduled tasks, you may wish to define it globaly in your plugin boot method to match the cms.backendTimezone config:

use Config;

...

public function boot()
{
    Config::set('app.schedule_timezone', config('cms.backendTimezone'));
}

Truth test constraints

The when method may be used to limit the execution of a task based on the result of a given truth test. In other words, if the given Closure return true, the task will execute as long as no other constraining conditions prevent the task from running:

$schedule->command('emails:send')->daily()->when(function () {
    return true;
});

#Preventing task overlaps

By default, scheduled tasks will be run even if the previous instance of the task is still running. To prevent this, you may use the withoutOverlapping method:

$schedule->command('emails:send')->withoutOverlapping();

In this example, the emails:send console command will be run every minute if it is not already running. The withoutOverlapping method is especially useful if you have tasks that vary drastically in their execution time, preventing you from needing to predict exactly how long a given task will take.

#Task output

The scheduler provides several convenient methods for working with the output generated by scheduled tasks. First, using the sendOutputTo method, you may send the output to a file for later inspection:

$schedule->command('emails:send')
    ->daily()
    ->sendOutputTo($filePath);

Using the emailOutputTo method, you may e-mail the output to an e-mail address of your choice. Note that the output must first be sent to a file using the sendOutputTo method. Also before e-mailing the output of a task, you should configure mail services:

$schedule->command('foo')
    ->daily()
    ->sendOutputTo($filePath)
    ->emailOutputTo('foo@example.com');

NOTE: The emailOutputTo and sendOutputTo methods are exclusive to the command method and are not supported for call.

#Task hooks

Using the before and after methods, you may specify code to be executed before and after the scheduled task is complete:

$schedule->command('emails:send')
    ->daily()
    ->before(function () {
        // Task is about to start...
    })
    ->after(function () {
        // Task is complete...
    });

#Pinging URLs

Using the pingBefore and thenPing methods, the scheduler can automatically ping a given URL before or after a task is complete. This method is useful for notifying an external service that your scheduled task is commencing or complete:

$schedule->command('emails:send')
    ->daily()
    ->pingBefore($url)
    ->thenPing($url);

You need to install Drivers plugin before you can use either the pingBefore($url) or thenPing($url) features.