GitHub - bayfrontmedia/cron-scheduler: A flexible framework-agnostic cron job scheduler using human-readable expressions.

Cron Scheduler

A flexible framework-agnostic cron job scheduler using human-readable expressions.

License
Author
Requirements
Installation
Usage

License

This project is open source and available under the MIT License.

Author

Requirements

PHP ^8.0

Installation

composer require bayfrontmedia/cron-scheduler

Usage

Start using Cron Scheduler

First, create a file to be used to schedule jobs, for example cron.php. The file can be named whatever you like.

Then, add a new entry to your crontab to run the file every minute:

* * * * * path/to/php/bin path/to/cron.php > /dev/null 2>&1

Or, to save the output from the jobs to a log file, specify a file path, such as:

* * * * * path/to/php/bin path/to/cron.php >> /path/to/cron-`date +\%Y-\%m-\%d`.log 2>&1

Now, your server will check the file every minute, and Cron Scheduler will only run the jobs that are due, according to their schedule.

Creating an instance

NOTE: All exceptions thrown by Cron Scheduler extend Bayfront\CronScheduler\CronException, so you can choose to catch exceptions as narrowly or broadly as you like.

The constructor accepts two parameters as strings: $lock_file_path and $output_file.

To prevent overlapping jobs, Cron Scheduler creates temporary "lock" files. These files are created for each job once it begins, and deleted once it completes. Jobs will be skipped when a lock file exists, even if it is due to run. If $lock_file_path === NULL, lock files will never be created, and all jobs will be allowed to overlap.

When an $output_file is specified, any output from the jobs that run will be saved to this file, unless a custom file is specified specifically for that job (see saveOutput). This has the same effect as specifying a log file in the crontab (see above).

The constructor may throw a Bayfront\CronScheduler\FilesystemException exception.

Example cron.php:

use Bayfront\CronScheduler\Cron;
use Bayfront\CronScheduler\FilesystemException;

try {

    $cron = new Cron('path/to/temp/dir', 'path/to/output/file.log');

} catch (FilesystemException $e) {
    die($e->getMessage());
}

Job schedule

at
everyMinutes
hourly
everyHours
daily
weekly
monthly
everyMonths
annually
sunday
monday
tuesday
wednesday
thursday
friday
saturday
january
february
march
april
may
june
july
august
september
october
november
december

getJobs

Description:

Return scheduled cron jobs.

Parameters:

(None)

Returns:

(array)

Example:

print_r($cron->getJobs());

getPreviousDate

Description:

Get previous date a given job was scheduled to run.

Parameters:

$label (string)
$date_format = 'Y-m-d H:i:s' (string): Date format to return

See: https://www.php.net/manual/en/datetime.format.php

Returns:

(string)

Throws:

Bayfront\CronScheduler\LabelExistsException
Bayfront\CronScheduler\SyntaxException

Example:

try {
    echo $cron->getPreviousDate('job-name');
    
} catch (CronException $e) {
    die($e->getMessage());
}

getNextDate

Description:

Get next date a given job is scheduled to run.

Parameters:

$label (string)
$date_format = 'Y-m-d H:i:s' (string): Date format to return

See: https://www.php.net/manual/en/datetime.format.php

Returns:

(string)

Throws:

Bayfront\CronScheduler\LabelExistsException
Bayfront\CronScheduler\SyntaxException

Example:

try {
    echo $cron->getNextDate('job-name');
    
} catch (CronException $e) {
    die($e->getMessage());
}

run

Description:

Runs all queued jobs that are due.

Parameters:

$current_time = 'now' (DateTimeInterface): Override current time by passing a DateTime instance with a given time.

Returns:

(array): Array of data relating to the completed jobs

Throws:

Bayfront\CronScheduler\FilesystemException

The array that is returned will contain the following keys:

jobs: Array of jobs that ran, each with their own start, end, elapsed and output keys.
start: Timestamp of when the jobs started.
end: Timestamp of when the jobs ended.
elapsed: Total seconds elapsed to complete jobs.
count: Number of jobs that ran.

Throws:

Bayfront\CronScheduler\FilesystemException

Example:

try {

    $result = $cron->run();

} catch (FilesystemException $e) {
    die($e->getMessage());
}

Another example, this time overriding (or, "spoofing") the current time:

$current_time = new DateTime('2020-09-08 10:55:00');

try {

    $result = $cron->run($current_time)

} catch (FilesystemException $e) {
    die($e->getMessage());
}

raw

Description:

Adds a raw command as a job.

By default, the job will run every minute.

Parameters:

$label (string): Unique label to assign to this job
$command (string)

Returns:

(self)

Throws:

Bayfront\CronScheduler\LabelExistsException

Example:

try {

    $cron->raw('job-name', 'php -v');

} catch (LabelExistsException $e) {
    die($e->getMessage());
}

php

Description:

Adds a php file as a job.

By default, the job will run every minute.

Parameters:

$label (string): Unique label to assign to this job
$file (string): Full path to file

Returns:

(self)

Throws:

Bayfront\CronScheduler\LabelExistsException

Example:

try {

    $cron->php('job-name', 'path/to/php/file.php');

} catch (LabelExistsException $e) {
    die($e->getMessage());
}

call

Description:

Adds a callable function as a job.

NOTE: Functions should return, not echo output.

By default, the job will run every minute.

Parameters:

$label (string): Unique label to assign to this job
$callable (callable)
$params = [] (array): Parameters to pass to the callable

Returns:

(self)

Throws:

Bayfront\CronScheduler\LabelExistsException

Example:

try {

    $cron->call('job-name', function($name) {
        return "Hello, " . $name . "\n\n";
    }, [
        'name' => 'John'
    ]);

} catch (LabelExistsException $e) {
    die($e->getMessage());
}

always

Description:

Always run job, even if previous execution is still in progress.

This prevents a lock file from being created for this job.

Parameters:

(None)

Returns:

(self)

Example:

try {

    $cron->php('job-name', 'path/to/php/file.php')->always();

} catch (LabelExistsException $e) {
    die($e->getMessage());
}

when

Description:

Add a condition for the job to run, even if it is due.

The job will only run if the return value of $callable is TRUE.

Parameters:

$callable (callable)
$params = [] (array)

Returns:

(self)

Example:

try {

    $cron->php('job-name', 'path/to/php/file.php')->when(function($return) {
        
        return $return;
       
    }, [
        'return' => true
    ]);

} catch (LabelExistsException $e) {
    die($e->getMessage());
}

saveOutput

Description:

Save the output of the job to a given file.

This will override $output_file, if specified in the constructor.

Parameters:

$output_file (string)

Returns:

(self)

Example:

try {

    $cron->php('job-name', 'path/to/php/file.php')->saveOutput('path/to/save/output.log');

} catch (LabelExistsException $e) {
    die($e->getMessage());
}

at

Description:

Schedule job to run using a valid cron expression.

Parameters:

$at (string)

Returns:

(self)

Example:

try {

    // 10:00pm Monday-Friday

    $cron->php('job-name', 'path/to/php/file.php')->at('0 22 * * 1-5');

} catch (LabelExistsException $e) {
    die($e->getMessage());
}

everyMinutes

Description:

Schedule job to run every x number of minutes.

Parameters:

$minutes = 1 (int)

Returns:

(self)

Throws:

Bayfront\CronScheduler\SyntaxException

Example:

try {

    $cron->php('job-name', 'path/to/php/file.php')->everyMinutes(5);

} catch (CronException $e) {
    die($e->getMessage());
}

hourly

Description:

Schedule job to run on a given minute of every hour.

Parameters:

$minute = 0 (int)

Returns:

(self)

Throws:

Bayfront\CronScheduler\SyntaxException

Example:

try {

    $cron->php('job-name', 'path/to/php/file.php')->hourly(15);

} catch (CronException $e) {
    die($e->getMessage());
}

everyHours

Description:

Schedule job to run on the hour every x number of hours.

Parameters:

$hours = 1 (int)

Returns:

(self)

Throws:

Bayfront\CronScheduler\SyntaxException

Example:

try {

    $cron->php('job-name', 'path/to/php/file.php')->everyHours(2);

} catch (CronException $e) {
    die($e->getMessage());
}

daily

Description:

Schedule job to run at a given time of every day.

Parameters:

$time = '00:00' (string): Time in 24-hour format without leading zeros

Returns:

(self)

Throws:

Bayfront\CronScheduler\SyntaxException

Example:

try {

    $cron->php('job-name', 'path/to/php/file.php')->daily('16:30');

} catch (CronException $e) {
    die($e->getMessage());
}

weekly

Description:

Schedule job to run on a given weekday and time of every week.

Parameters:

$weekday = 0 (int): 0-6 as Sunday-Saturday
$time = '00:00' (string): Time in 24-hour format without leading zeros

Returns:

(self)

Throws:

Bayfront\CronScheduler\SyntaxException

Example:

try {

    // 4:30pm every Friday

    $cron->php('job-name', 'path/to/php/file.php')->weekly(5, '16:30');

} catch (CronException $e) {
    die($e->getMessage());
}

monthly

Description:

Schedule job to run on a given day and time of every month.

Parameters:

$day = 1 (int): 1-31 as day of the month
$time = '00:00' (string): Time in 24-hour format without leading zeros

Returns:

(self)

Throws:

Bayfront\CronScheduler\SyntaxException

Example:

try {

    // Midnight on the 15th day of every month

    $cron->php('job-name', 'path/to/php/file.php')->monthly(15);

} catch (CronException $e) {
    die($e->getMessage());
}

everyMonths

Description:

Schedule job to run at a given time on the first day every x number of months.

Parameters:

$months = 1 (int)
$time = '00:00' (string): Time in 24-hour format without leading zeros

Returns:

(self)

Throws:

Bayfront\CronScheduler\SyntaxException

Example:

try {

    // 9am on the first day every of every third month

    $cron->php('job-name', 'path/to/php/file.php')->everyMonths(3, '9:00');

} catch (CronException $e) {
    die($e->getMessage());
}

annually

Description:

Schedule job to run on a given month, day and time each year.

Parameters:

$month = 1 (int)
$day = 1 (int)
$time = '00:00' (string): Time in 24-hour format without leading zeros

Returns:

(self)

Throws:

Bayfront\CronScheduler\SyntaxException

Example:

try {

    // Midnight every June 20th

    $cron->php('job-name', 'path/to/php/file.php')->annually(6, 20);

} catch (CronException $e) {
    die($e->getMessage());
}

sunday

Description:

Schedule job to run at a given time every Sunday.

Parameters:

$time = '00:00' (string): Time in 24-hour format without leading zeros

Returns:

(self)

Throws:

Bayfront\CronScheduler\SyntaxException

Example:

try {

    // Midnight every Sunday

    $cron->php('job-name', 'path/to/php/file.php')->sunday();

} catch (CronException $e) {
    die($e->getMessage());
}

monday

Description:

Schedule job to run at a given time every Monday.

Parameters:

$time = '00:00' (string): Time in 24-hour format without leading zeros

Returns:

(self)

Throws:

Bayfront\CronScheduler\SyntaxException

Example:

try {

    // Midnight every Monday

    $cron->php('job-name', 'path/to/php/file.php')->monday();

} catch (CronException $e) {
    die($e->getMessage());
}

tuesday

Description:

Schedule job to run at a given time every Tuesday.

Parameters:

$time = '00:00' (string): Time in 24-hour format without leading zeros

Returns:

(self)

Throws:

Bayfront\CronScheduler\SyntaxException

Example:

try {

    // Midnight every Tuesday

    $cron->php('job-name', 'path/to/php/file.php')->tuesday();

} catch (CronException $e) {
    die($e->getMessage());
}

wednesday

Description:

Schedule job to run at a given time every Wednesday.

Parameters:

$time = '00:00' (string): Time in 24-hour format without leading zeros

Returns:

(self)

Throws:

Bayfront\CronScheduler\SyntaxException

Example:

try {

    // Midnight every Wednesday

    $cron->php('job-name', 'path/to/php/file.php')->wednesday();

} catch (CronException $e) {
    die($e->getMessage());
}

thursday

Description:

Schedule job to run at a given time every Thursday.

Parameters:

$time = '00:00' (string): Time in 24-hour format without leading zeros

Returns:

(self)

Throws:

Bayfront\CronScheduler\SyntaxException

Example:

try {

    // Midnight every Thursday

    $cron->php('job-name', 'path/to/php/file.php')->thursday();

} catch (CronException $e) {
    die($e->getMessage());
}

friday

Description:

Schedule job to run at a given time every Friday.

Parameters:

$time = '00:00' (string): Time in 24-hour format without leading zeros

Returns:

(self)

Throws:

Bayfront\CronScheduler\SyntaxException

Example:

try {

    // Midnight every Friday

    $cron->php('job-name', 'path/to/php/file.php')->friday();

} catch (CronException $e) {
    die($e->getMessage());
}

saturday

Description:

Schedule job to run at a given time every Saturday.

Parameters:

$time = '00:00' (string): Time in 24-hour format without leading zeros

Returns:

(self)

Throws:

Bayfront\CronScheduler\SyntaxException

Example:

try {

    // Midnight every Saturday

    $cron->php('job-name', 'path/to/php/file.php')->saturday();

} catch (CronException $e) {
    die($e->getMessage());
}

january

Description:

Schedule job to run on a given day and time each January.

Parameters:

$day = 1 (int)
$time = '00:00' (string): Time in 24-hour format without leading zeros

Returns:

(self)

Throws:

Bayfront\CronScheduler\SyntaxException

Example:

try {

    // 11:30pm every January 10th

    $cron->php('job-name', 'path/to/php/file.php')->january(10, '23:30');

} catch (CronException $e) {
    die($e->getMessage());
}

february

Description:

Schedule job to run on a given day and time each February.

Parameters:

$day = 1 (int)
$time = '00:00' (string): Time in 24-hour format without leading zeros

Returns:

(self)

Throws:

Bayfront\CronScheduler\SyntaxException

Example:

try {

    // 11:30pm every February 10th

    $cron->php('job-name', 'path/to/php/file.php')->february(10, '23:30');

} catch (CronException $e) {
    die($e->getMessage());
}

march

Description:

Schedule job to run on a given day and time each March.

Parameters:

$day = 1 (int)
$time = '00:00' (string): Time in 24-hour format without leading zeros

Returns:

(self)

Throws:

Bayfront\CronScheduler\SyntaxException

Example:

try {

    // 11:30pm every March 10th

    $cron->php('job-name', 'path/to/php/file.php')->march(10, '23:30');

} catch (CronException $e) {
    die($e->getMessage());
}

april

Description:

Schedule job to run on a given day and time each April.

Parameters:

$day = 1 (int)
$time = '00:00' (string): Time in 24-hour format without leading zeros

Returns:

(self)

Throws:

Bayfront\CronScheduler\SyntaxException

Example:

try {

    // 11:30pm every April 10th

    $cron->php('job-name', 'path/to/php/file.php')->april(10, '23:30');

} catch (CronException $e) {
    die($e->getMessage());
}

may

Description:

Schedule job to run on a given day and time each May.

Parameters:

$day = 1 (int)
$time = '00:00' (string): Time in 24-hour format without leading zeros

Returns:

(self)

Throws:

Bayfront\CronScheduler\SyntaxException

Example:

try {

    // 11:30pm every May 10th

    $cron->php('job-name', 'path/to/php/file.php')->may(10, '23:30');

} catch (CronException $e) {
    die($e->getMessage());
}

june

Description:

Schedule job to run on a given day and time each June.

Parameters:

$day = 1 (int)
$time = '00:00' (string): Time in 24-hour format without leading zeros

Returns:

(self)

Throws:

Bayfront\CronScheduler\SyntaxException

Example:

try {

    // 11:30pm every June 10th

    $cron->php('job-name', 'path/to/php/file.php')->june(10, '23:30');

} catch (CronException $e) {
    die($e->getMessage());
}

july

Description:

Schedule job to run on a given day and time each July.

Parameters:

$day = 1 (int)
$time = '00:00' (string): Time in 24-hour format without leading zeros

Returns:

(self)

Throws:

Bayfront\CronScheduler\SyntaxException

Example:

try {

    // 11:30pm every July 10th

    $cron->php('job-name', 'path/to/php/file.php')->july(10, '23:30');

} catch (CronException $e) {
    die($e->getMessage());
}

august

Description:

Schedule job to run on a given day and time each August.

Parameters:

$day = 1 (int)
$time = '00:00' (string): Time in 24-hour format without leading zeros

Returns:

(self)

Throws:

Bayfront\CronScheduler\SyntaxException

Example:

try {

    // 11:30pm every August 10th

    $cron->php('job-name', 'path/to/php/file.php')->august(10, '23:30');

} catch (CronException $e) {
    die($e->getMessage());
}

september

Description:

Schedule job to run on a given day and time each September.

Parameters:

$day = 1 (int)
$time = '00:00' (string): Time in 24-hour format without leading zeros

Returns:

(self)

Throws:

Bayfront\CronScheduler\SyntaxException

Example:

try {

    // 11:30pm every September 10th

    $cron->php('job-name', 'path/to/php/file.php')->sepember(10, '23:30');

} catch (CronException $e) {
    die($e->getMessage());
}

october

Description:

Schedule job to run on a given day and time each October.

Parameters:

$day = 1 (int)
$time = '00:00' (string): Time in 24-hour format without leading zeros

Returns:

(self)

Throws:

Bayfront\CronScheduler\SyntaxException

Example:

try {

    // 11:30pm every October 10th

    $cron->php('job-name', 'path/to/php/file.php')->october(10, '23:30');

} catch (CronException $e) {
    die($e->getMessage());
}

november

Description:

Schedule job to run on a given day and time each November.

Parameters:

$day = 1 (int)
$time = '00:00' (string): Time in 24-hour format without leading zeros

Returns:

(self)

Throws:

Bayfront\CronScheduler\SyntaxException

Example:

try {

    // 11:30pm every November 10th

    $cron->php('job-name', 'path/to/php/file.php')->november(10, '23:30');

} catch (CronException $e) {
    die($e->getMessage());
}

december

Description:

Schedule job to run on a given day and time each December.

Parameters:

$day = 1 (int)
$time = '00:00' (string): Time in 24-hour format without leading zeros

Returns:

(self)

Throws:

Bayfront\CronScheduler\SyntaxException

Example:

try {

    // 11:30pm every December 10th

    $cron->php('job-name', 'path/to/php/file.php')->december(10, '23:30');

} catch (CronException $e) {
    die($e->getMessage());
}

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
.github		.github
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
composer.json		composer.json

License

bayfrontmedia/cron-scheduler

Folders and files

Latest commit

History

Repository files navigation

Cron Scheduler

License

Author

Requirements

Installation

Usage

Start using Cron Scheduler

Creating an instance

Public methods

getJobs

getPreviousDate

getNextDate

run

raw

php

call

always

when

saveOutput

at

everyMinutes

hourly

everyHours

daily

weekly

monthly

everyMonths

annually

sunday

monday

tuesday

wednesday

thursday

friday

saturday

january

february

march

april

may

june

july

august

september

october

november

december

About

Topics

Resources

License

Security policy

Stars

Watchers

Forks

Releases 8

Packages 0

Languages

Packages