thamtech / yii2-scheduler
A configuration-driven scheduled task runner for Yii2 applications
Fund package maintenance!
Liberapay
Installs: 1 920
Dependents: 0
Suggesters: 0
Security: 0
Stars: 7
Watchers: 2
Forks: 3
Open Issues: 1
Type:yii2-extension
Requires
- dragonmantank/cron-expression: ~1.2 || ~2.0 || ~3.0
- yiisoft/yii2: ^2.0.14 <2.1
Requires (Dev)
README
A configuration-driven scheduled task manager for Yii2.
This is adapted from webtoolsnz/yii2-scheduler to provide a more configuration-driven approach.
The main differences:
- webtoolsnz/yii2-scheduler
- automatically picks up Task classes in the
@app/tasks
folder - once tasks have been established in the database table, the
active
value from the database controls whether the task is enabled, not theactive
property in the Task class
- automatically picks up Task classes in the
- thamtech/yii2-scheduler
- tasks are defined explicitly as part of the scheduler module config
- the
active
property of the Task instance controls whether the task is enabled (so that it may be controlled programmatically instead of only via the scheduler's databse table)
Installation
The preferred way to install this extension is through composer.
Install using the following command.
$ composer require thamtech/yii2-scheduler
Now that the package has been installed you need to configure the module in your application.
The config/console.php
file (or the equivalent console config file if you are
using a different Yii project template) should be updated to reflect the changes
below:
<?php [ 'bootstrap' => ['log', 'scheduler'], 'modules' => [ 'scheduler' => [ 'class' => 'thamtech\scheduler\Module', // optional: define a mutex component to acquire a lock // while executing tasks so only one execution of schedule tasks // can be running at a time. 'mutex' => [ 'class' => 'yii\mutex\MysqlMutex', ], // OR optionally reference an existing application mutex component, // for example, one named "mutex": // 'mutex' => 'mutex', ], ], 'components' => [ 'log' => [ 'traceLevel' => YII_DEBUG ? 3 : 0, 'targets' => [ [ 'class' => 'yii\log\EmailTarget', 'mailer' =>'mailer', 'levels' => ['error', 'warning'], 'message' => [ 'to' => ['alets@example.com'], 'from' => ['app@example.com'], 'subject' => 'Scheduler Error - ####SERVERNAME####' ], 'except' => [ ], ], ], ], ], ];
also add this to the top of your config/console.php
file:
\yii\base\Event::on( \thamtech\scheduler\console\SchedulerController::className(), \thamtech\scheduler\events\SchedulerEvent::EVENT_AFTER_RUN, function ($event) { if (!$event->success) { foreach($event->exceptions as $exception) { throw $exception; } } } );
Run the database migrations, which will create the necessary tables:
php yii migrate up --migrationPath=vendor/thamtech/yii2-scheduler/src/migrations
To implement the GUI for reviewing scheduled tasks and logs, add a web controller:
<?php namespace app\modules\admin\controllers; use yii\web\Controller; /** * SchedulerController has a set of actions for viewing scheduled tasks and * their logs. */ class SchedulerController extends Controller { public function actions() { return [ 'index' => [ 'class' => 'thamtech\scheduler\actions\IndexAction', 'view' => '@scheduler/views/index', ], 'view' => [ 'class' => 'thamtech\scheduler\actions\ViewAction', 'view' => '@scheduler/views/view', ], 'view-log' => [ 'class' => 'thamtech\scheduler\actions\ViewLogAction', 'view' => '@scheduler/views/view-log', ], ]; } }
Example Task
You can now create your first task using scheduler. In this example, we will
create ConcatStringsTask.php
inside the tasks
directory of your app:
<?php namespace app\tasks; /** * Task to print a concatenation of the specified strings. */ class ConcatStringsTask extends \thamtech\scheduler\Task { /** * @var string task description */ public $description = 'Prints a concatenation of the specified strings'; /** * @var string[] the strings to be concatenated */ public $strings = []; /** * @inheritdoc */ public function run() { echo join('', $this->strings); } }
In your scheduler
module config within your console app, define the task:
<?php 'modules' => [ 'scheduler' => [ 'class' => 'thamtech\scheduler\Module', 'tasks' => [ 'hello-world' => [ 'class' => 'app\tasks\ConcatStringsTask', 'displayName' => 'Hello World Task', 'schedule' => '0 * * * *', 'strings' => ['Hello', ' ', 'World'], ], ], ], ],
The above code defines a simple task that runs at the start of every hour, and
prints "Hello World". An alternative approach would be to hard-code some or all
of the properties in your task class (like schedule
). However, this example
is more in line with the project's goal of being a more configuration-driven
approach to defining tasks.
The $schedule
property of this class defines how often the task will run,
these are simply Cron Expression
You can define multiple task instances in the scheduler
module config, and it
is ok to reuse the same Task class for multiple instances. Here is an example
with an additional "Foo Bar" task that runs every hour on the half-hour:
<?php 'modules' => [ 'scheduler' => [ 'class' => 'thamtech\scheduler\Module', 'tasks' => [ 'hello-world' => [ 'class' => 'app\tasks\ConcatStringsTask', 'displayName' => 'Hello World Task', 'schedule' => '0 * * * *', 'strings' => ['Hello', ' ', 'World'], ], 'foo-bar' => [ 'class' => 'app\tasks\ConcatStringsTask', 'displayName' => 'Foo Bar Task', 'schedule' => '30 * * * *', 'strings' => ['Foo', ' ', 'Bar'], ], ], ], ],
Running the tasks
Scheduler provides an intuitive CLI for executing tasks, below are some examples
# list all tasks and their status $ php yii scheduler # run the task if due $ php yii scheduler/run --taskName=hello-world # force the task to run regardless of schedule $ php yii scheduler/run --taskName=hello-world --force # run all tasks $ php yii scheduler/run-all # force all tasks to run $ php yii scheduler/run-all --force
In order to have your tasks run automatically simply setup a crontab like so
*/5 * * * * admin php /path/to/my/app/yii scheduler/run-all > /dev/null &
Events & Errors
Events are thrown before and running individual tasks as well as at a global level for multiple tasks
Task Level
<?php Event::on(AlphabetTask::className(), AlphabetTask::EVENT_BEFORE_RUN, function ($event) { Yii::trace($event->task->className . ' is about to run'); }); Event::on(AlphabetTask::className(), AlphabetTask::EVENT_AFTER_RUN, function ($event) { Yii::trace($event->task->className . ' just ran '.($event->success ? 'successfully' : 'and failed')); });
or at the global level, to throw errors in /yii
<?php $application->on(\thamtech\scheduler\events\SchedulerEvent::EVENT_AFTER_RUN, function ($event) { if (!$event->success) { foreach($event->exceptions as $exception) { throw $exception; } } });
You could throw the exceptions at the task level, however this will prevent further tasks from running.
License
The MIT License (MIT). Please see LICENSE.md for more information.