README

Minimalistic Cron job manager. Register jobs and the job manager will execute them automatically depending on their interval.

NOTE: This is not a queue manager and therefore this has nothing to do with Laravel's queue component. Also note that Laravel 5 has an integrated task scheduler that works similar to this library.

Installation

This library requires PHP >= 7.0

Add chriskonnertz/jobs to composer.json:

"chriskonnertz/jobs": "3.*"

Or via a console:

composer require chriskonnertz/jobs

In the future run composer update to update to the latest version of this library.

Framework support

This library supports Laravel >=5.5 with a service provider. Add the service provider to the config file config/app.php:

    'providers' => array(
        // ...
        'ChrisKonnertz\Jobs\Integration\JobsServiceProvider',
    ),

To create an alias for the facade, add this new entry in this file:

    'aliases' => array(
        // ...
        'Jobs' => 'ChrisKonnertz\Jobs\Integration\JobsFacade',
        'AbstractJob' => 'ChrisKonnertz\Jobs\AbstractJob',
    ),

Introduction

Create a concrete job class:

    class ExampleJob extends ChrisKonnertz\Jobs\AbstractJob 
    {

        protected $name = 'exampleJob';

        protected $interval = 5; // Run every five minutes

        public function run(int $executedAt = null)
        {
            echo 'Hello World!';
        }

    }

Instantiate the job manager:

    $cache = new ExampleCacheClass;
    $jobs = new ChrisKonnertz\Jobs\Jobs($cache);

If you use Laravel with the service provider you do not have to worry about this. The service provider will inject the cache dependency. In any other case the cache class has to implement the cache interface (CacheInterface). Take a look at the LaravelCache class (that is meant for Laravel integration) for an example implementation.

Register the job:

    $jobs->addLazy('updateStreams', 'ExampleJob');

Execute the registered jobs:

    $jobs->run();

Automatically execute jobs

If your application is built on top of Laravel, you will have access to an Artisan command: php artisan jobs This command will call Jobs::run() to execute the jobs. Therefore you can add a Cron job to the crontab to start the command, for example 1 * * * * php /var/www/laravel/artisan jobs. This will execute the Artisan command every minute. We recommend to run the Cron job every minute.

Methods of the jobs manager

Note: Some of these methods may throw a JobException.

Determine if a job exists in the pool

    $hasJob = $jobs->has('exampleJob');

Add a job to the pool (without lazy loading)

    $job = new ExampleJob;
    $jobs->add($job);

Add a job to the pool (with lazy loading)

    // Pass the class name:
    $jobs->addLazy(\My\Example\Job::class);

    // Or pass a closure:
    $jobs->addLazy(function()
    {
        return new ExampleJob;
    });

We recommend using addLazy() over add().

Remove a job from the pool

    $jobs->remove('exampleJob');

Remove all jobs from the pool

    $jobs->clear();

Count the jobs

    $howMany = $jobs->count();

Get the remaining cool down

$minutes = $jobs->remainingCoolDown();

Get the timestamp of the last iteration

$timestamp =  $jobs->lastRunAt();

Set the minimum cool down time for all jobs

    $jobs->coolDown(1); // One minute

The minimum value and the initial value is one minute. Most likely there is no reason to change this value ever.

Set the cache key namespace

    $jobs->cacheKey('jobs.');

The job class

A job class implements the job interface. Therefore it has to implement these methods:

    interface JobInterface 
    {

        public function getName() : string; // The name (identifier) of the job

        public function getActive() : bool; // Active or paused (=not executed)?

        public function getInterval() : int; // The cool down time

        public function run(int $executedAt = null); // The run method

    }

The AbstractJob class actually implements these methods so we recommend to let your concrete job classes inherit from this class. The abstract class provides the attributes name, active and interval that inheriting classes may overwrite.

The interval

Per default (as long as the inheriting job class does not overwrite it) the getInterval() is a simple getter for the interval attribute. The interval attribute defines the duration of the job's cool down in minutes. For example if it is 60 minutes (= 1 hour) the job is executed once per hour (max).

Status

Status of this repository: Deprecated. Issues will be fixed but no new feature implemented.