Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/enscope/yii2-scheduler

Yet another Yii2 Cron-like extension
https://github.com/enscope/yii2-scheduler

scheduled-tasks task-scheduler yii2 yii2-cron yii2-extension yii2-scheduler

Last synced: 27 days ago
JSON representation

Yet another Yii2 Cron-like extension

Awesome Lists containing this project

README 

        
# 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.