bayfrontmedia / cron-scheduler
A flexible framework-agnostic cron job scheduler using human-readable expressions.
Installs: 1 494
Dependents: 1
Suggesters: 0
Security: 0
Stars: 1
Watchers: 2
Forks: 1
Open Issues: 0
Requires
- php: ^8.0
- bayfrontmedia/php-string-helpers: ^2.0
- dragonmantank/cron-expression: 3.3.*
README
A flexible framework-agnostic cron job scheduler using human-readable expressions.
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());
}
Public methods
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 aDateTime
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 ownstart
,end
,elapsed
andoutput
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());
}