herroffizier / yiiq
Background job manager for Yii
Requires
- php: >=5.4
- ext-pcntl: *
- codemix/yiiredis: dev-master
Requires (Dev)
- ext-xdebug: *
- brianium/paratest: dev-master
- phing/phing: dev-master
- phpunit/dbunit: *
- phpunit/php-invoker: *
- phpunit/phpunit: ~3
- phpunit/phpunit-selenium: *
- phpunit/phpunit-story: *
- squizlabs/php_codesniffer: dev-master
- yiisoft/yii: ~1
This package is not auto-updated.
Last update: 2024-11-05 03:32:26 UTC
README
Yiiq is a powerful Redis-backed multithreaded background job manager for Yii Framework designed with stability and simplicity in mind.
To run a job just wrap it in class and type:
Yii::app()->yiiq->enqueue('\MyJob');
And it's done!
Table of contents
Features
- Stability
If job crashed, daemon stays alive. If server crashed, daemon recovers its state with all unfinished jobs. - Multithreading
You can run as many processes as you need. - Queueing
Jobs may be grouped in different queues which handled by different processes. - Clarity
You can track your job status at every point of time. - Scheduling
Jobs may be executed at certain time or immediately. Once or many times. - Feedback
Jobs may return result back to the extension.
Requirements
- Unix platform
- PHP >= 5.4
- Redis
- pcntl extension
- Yii Framework >= 1.1.14
- YiiRedis
Installation
Following steps are described assuming the fact that you have default Yii application layout, which contains two config files: main.php
and console.php
for web and console applications accordingly. Yiiq consists of two main parts too: framework extension and daemon. Extension queues jobs and daemon executes them. In view of the fact that daemon acts as console application, it will use console.php
config file, whilst extension will use both files depending on application type in which it's being used. So pay attention to the fact that Yiiq and YiiRedis extensions must be included in both files.
At first, install Yiiq via Composer:
composer require herroffizier/yiiq:dev-master
At this point make sure that vendor/autoload.php
is included in both config files.
Now we need to set up extension. Add it to your components
array (must be added in both files also):
'components' => array( // ... 'yiiq' => array( 'class' => '\Yiiq\Yiiq', // Name to identify daemon in process list (optional) 'name' => 'Yiiq test instance', ), // ... ),
Note, that YiiRedis extension must be loaded in both files too!
Finally, add following commands to commandMap
in console.php
:
'commandMap' => array( // ... // Control Yiiq command 'yiiq' => array( 'class' => '\Yiiq\commands\Main', ), // Daemon Yiiq command 'yiiqWorker' => array( 'class' => '\Yiiq\commands\Worker', ), // ... ),
Now it's time to run daemon. Remember, daemon is responsible for job executing, therefore it must be runnign all the time. Type following command in protected
folder of your application.
./yiic yiiq start --log=yiiq.log
log
parameter is optional but it highly recommended for first run at least.
Run ./yiic yiiq status
to check if daemon started correctly. You should see something like this:
All processes (28235) are alive. Everything looks good.
If daemon is not running refer to application.log
and yiiq.log
(both stored in runtime
folder) for details.
Usage
Creating jobs
To create a job you should extend \Yiiq\jobs\Payload
class and implement it's run()
method:
class YiiqDummyJob extends \Yiiq\jobs\Payload { /** * Time to wait before exit. * * @var integer */ public $sleep = 10; /** * This method should contain all the job logic. * * @return {mixed} all returned data will be saved in Redis * (for non-repeatable jobs) */ public function run() { Yii::trace( 'Started dummy job '.$this->queue.':'.$this->id .' (sleep for '.$this->sleep.'s).' ); sleep($this->sleep); Yii::trace('Job '.$this->queue.':'.$this->id.' completed.'); } }
In fact there are three types of jobs in Yiiq: simple, scheduled and repeatable. First one executed immediately, second one will execute at certain time, and third one will run infinitely in accordance with specified interval.
Simple job
To add a simple job you may use one of following calls. As you already know, this job will be executed as soon as possible and only once.
// Add YiiqDummyJob with default arguments to default queue. // Via arguments: $job = Yii::app()->yiiq->enqueue('\YiiqDummyJob'); // Via method chaining: $job = Yii::app()->yiiq-> create('\YiiqDummyJob')-> enqueue(); // Add YiiqDummyJob with customized arguments to default queue. // Via arguments: $job = Yii::app()->yiiq->enqueue( '\YiiqDummyJob', ['sleep' => 5] ); // Via method chaining: $job = Yii::app()->yiiq-> create('\YiiqDummyJob')-> withArgs(['sleep' => 5])-> enqueue(); // Add YiiqDummyJob with customized arguments to 'custom' queue. // Via arguments: $job = Yii::app()->yiiq->enqueue( '\YiiqDummyJob', ['sleep' => 5], 'custom' ); // Via method chaining: $job = Yii::app()->yiiq-> create('\YiiqDummyJob')-> into('custom')-> withArgs(['sleep' => 5])-> enqueue();
Scheduled job
To schedule a job at certain time, you must specify time or interval:
// Run job at certain time. // Via arguments: $job = Yii::app()->yiiq->enqueueAt( time() + 60, 'YiiqDummyJob' ); // Via method chaining: $job = Yii::app()->yiiq-> create('\YiiqDummyJob')-> runAt(time() + 60)-> enqueue(); // Run job after 60 seconds. In fact exactly the same as above. // Via arguments: $job = Yii::app()->yiiq->enqueueAfter( 60, '\YiiqDummyJob' ); // Via method chaining: $job = Yii::app()->yiiq-> create('\YiiqDummyJob')-> runAt(time() + 60)-> enqueue();
Repeatable job
To create a repeatable job, you may use following code:
// Run job each 300 seconds. // Via arguments: $job = Yii::app()->yiiq->enqueueEach( 300, '\YiiqDummyJob' ); // Via method chaining: $job = Yii::app()->yiiq-> create('\YiiqDummyJob')-> runEach(300)-> enqueue();
Note that repeatable job cannot return any data back to Yiiq.