Download the PHP package enscope/yii2-scheduler without Composer
On this page you can find all versions of the php package enscope/yii2-scheduler. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package yii2-scheduler
yii2-scheduler
Yet another Yii2 Cron-like extension, which was created because I felt, I needed something else, that was available at the time. In case you like it, feel free to use it in your projects. Currently, it is running in production successfully for multiple months.
Basic Usage
Add ConsoleController
to controllerMap
in your config.php
:
'controllerMap' => [
...
'scheduler' => [
'class' => \enscope\Scheduler\ConsoleController::className(),
'tasks' => require dirname(__FILE__) . '/schedule.php',
],
...
],
Tasks can be loaded from external file or in-lined in config.php
.
Externalizing the tasks is recommended, then schedule.php
can be like:
return [
[
'schedule' => '0 2 * * 1-5',
'class' => 'Main\Notifications\ScheduledTask\NotificationsDigestTask',
],
[
'schedule' => '* * * * *',
'class' => 'enscope\Scheduler\ScheduledTask\RunActionScheduledTask',
'action' => 'mailer/send',
'params' => [
'quiet' => true,
],
],
];
This scheduler configuration contains two tasks, one that is run every work-day at 2am and one that is run each minute.
As you can see, you can either reference class, sub-classing BaseScheduledTask
(in principe, the task must implement ScheduledTaskInteface
,
allowing customization of the schedule configuration, but it is recommended to extend BaseScheduledTask
and use
default CRON-like configuration) or call any available action from another controller.
Tasks are executed in order of definition, as are present in tasks
array.
The scheduler itself should be run using CRON or other task scheduler and to allow for the most granularity, it should be run each minute.
Scheduled Task Configuration
Configuration of scheduled tasks closely follows CRON-like principles. The schedule configuration string is 5 part definition in following order:
* * * * *
^ ^ ^ ^ ^ day of week (0-6)
| | | | month (1-12)
| | | day of month (1-31)
| | hour (0-23)
| minute (0-59)
You can define intervals using hyphen, e.g. 0 2 * * 1-5
to run the task 2AM on weekdays,
you can define cycles using slash, e.g. */5 * * * *
to run the task "every five minutes",
you can specify multiple values separated by comma, e.g. * 6,12,18 * * *
to run the task every 6 hours except midnight.
Implementing Custom Tasks
All scheduled tasks must implement ScheduledTaskInterface
, but this interface does not provide actual evaluation of correct time to run the task
and will run the task every time, the scheduler is run.
This basic interface is simple:
interface ScheduledTaskInterface
{
/**
* Executes scheduled task, but task must determine, if it will
* perform the job or not, based on internal scheduling mechanism.
*
* @param \DateTime $time Time of the scheduler invocation, that may be different
* from the current time, but all schedules must relate
* to this time when checking if schedule is satisfied
* @param bool $force If true, task should run regardless of schedule
*
* @return bool TRUE, if the task was actually executed
*/
public function execute(\DateTime $time, $force = false);
}
The comment says it all. To implement a scheduled task, you need to implement execute(DateTime, boolean = false)
method.
The task itself has no connection to task scheduler, it should have the configuration of the schedule included in itself.
Simplicity of the interface is by design, to allow for more advanced scheduled task configuration, if ever needed.
For most use-cases, it is sufficient to extend abstract BaseScheduledTask
, which contains single abstract method
scheduledTask()
, that needs to be implemented. The class implements execute(..)
method and evaluates satisfaction
of the schedule
automatically, running the task only when the conditions are satisfied (and the task is not forced).
Exceptions and Error Handling
Task can throw any Exception and the Scheduler will handle it, reporting error on error output along with scheduled task name
and exception message. After reporting the error, Scheduler will continue running other tasks in order as defined. If it is
necessary to terminate Scheduler
execution immediatelly, it is possible to use TerminateScheduleException
, which will
force Scheduler
to terminate instantly with appropriate error message. Of course, another Scheduler execution will
try to run tasks again.