Laravel Task Scheduler: Limiting the Execution of Tasks

It is possible to limit the execution of tasks based on some criteria that developers define, as well as limit a tasks execution based on the current environment.

#Limit Task Environments

Limiting the environments the task can run in is done using the environments($environments) method. This method accepts either an array or multiple method parameters. The following example demonstrates how to use the environments method:

 1<?php
 2 
 3// ...
 4 
 5protected function schedule(Schedule $schedule)
 6{
 7    // Using multiple method parameters.
 8    $schedule->command('command:name --options')
 9             ->daily()
10             ->environments('production', 'local');
11 
12    // Using an array.
13    $schedule->command('command:name --options')
14            ->daily()
15            ->environments([
16                'production',
17                'local'
18            ]);
19}
20 
21// ...

The environments method mutates a public property named $environments. This property can be accessed directly if needed:

 1<?php
 2 
 3// ...
 4 
 5protected function schedule(Schedule $schedule)
 6{
 7    // Schedule an event while limiting the environment.
 8    $event = $schedule->command('command:name --options')
 9                      ->environments('production', 'local');
10 
11    // Access the environments directly.
12    $environments = $event->environments;
13}
14 
15// ...

After the previous code has executed, the $environments variable would store an array with the items production and local.

#Filtering Tasks

Tasks can also be quickly filtered using callback functions. These filters are checked directly by the Illuminate\Console\Scheduling\ScheduleRunCommand command. This command calls a public method filtersPass on each task that is due to run at any given time.

There are two methods used to filter a task: the when(Closure $closure) method and the skip(Closure $closure) method. The when method is typically used to determine that a task should run, and the skip method is the logical opposite, deciding when the task should not run. Both of these methods must return either true or false as their only return values.

When using the when method, a return value of true indicates that the task should run, and a return value of false indicates that a task should not be ran. In the following example, the task would not be skipped since the return value is true.

 1<?php
 2 
 3// ...
 4 
 5protected function schedule(Schedule $schedule)
 6{
 7    $schedule->command('command:name --options')
 8             ->when(function() {
 9                // Some logic to determine if the task should run.
10                return true;
11             });
12}
13 
14// ...

The skip method is the logical opposite of the when method. In the following code example, the task would be skipped because the skip method returns true:

 1<?php
 2 
 3// ...
 4 
 5protected function schedule(Schedule $schedule)
 6{
 7    $schedule->command('command:name --options')
 8             ->skip(function() {
 9                // Some logic to determine if the task should be skipped.
10                return true;
11             });
12}
13 
14// ...

Like the before and after methods, it is possible to supply multiple filters to the Event instance. Additionally, the before and after methods support method parameter injection as well.

The following example demonstrates using multiple task filters:

 1<?php
 2 
 3use Illuminate\Contracts\Mail\Mailer;
 4 
 5// ...
 6 
 7protected function schedule(Schedule $schedule)
 8{
 9    // Registering multiple 'skip' filters.
10    $schedule->command('command:name --options')
11             ->skip(function() {
12                // First skip filter.
13             })
14             ->skip(function() {
15                // Second skip filter.
16             });
17 
18    // Registering multiple 'when' filters.
19    $schedule->command('command:name --options')
20             ->when(function() {
21                // First when filter.
22             })
23             ->when(function() {
24                // Second when filter.
25             });
26 
27    // Registering filters using method injection.
28    $schedule->command('command:name --options')
29             ->when(function(Mailer $mail) {
30                // A when filter with access
31                // to a Mailer instance.
32             });
33}
34 
35// ...

∎