\CronCronExpression

CRON expression parser that can determine whether or not a CRON expression is due to run, the next run date and previous run date of a CRON expression.

The determinations made by this class are accurate if checked run once per minute (seconds are dropped from date time comparisons).

Schedule parts must map to: minute [0-59], hour [0-23], day of month, month [1-12|JAN-DEC], day of week [1-7|MON-SUN], and an optional year.

Summary

Methods
Properties
Constants
factory()
isValidExpression()
__construct()
setExpression()
setPart()
setMaxIterationCount()
getNextRunDate()
getPreviousRunDate()
getMultipleRunDates()
getExpression()
__toString()
isDue()
No public properties found
MINUTE
HOUR
DAY
MONTH
WEEKDAY
YEAR
getRunDate()
No protected properties found
N/A
No private methods found
$cronParts
$fieldFactory
$maxIterationCount
$order
N/A

Constants

MINUTE

MINUTE = 0

HOUR

HOUR = 1

DAY

DAY = 2

MONTH

MONTH = 3

WEEKDAY

WEEKDAY = 4

YEAR

YEAR = 5

Properties

$cronParts

$cronParts : array

Type

array — CRON expression parts

$fieldFactory

$fieldFactory : \Cron\FieldFactory

Type

\Cron\FieldFactory — CRON field factory

$maxIterationCount

$maxIterationCount : integer

Type

integer — Max iteration count when searching for next run date

$order

$order : array

Type

array — Order in which to test of cron parts

Methods

factory()

factory(string  $expression, \Cron\FieldFactory  $fieldFactory = null) : \Cron\CronExpression

Factory method to create a new CronExpression.

Parameters

string $expression

The CRON expression to create. There are several special predefined values which can be used to substitute the CRON expression:

 `@yearly`, `@annually` - Run once a year, midnight, Jan. 1 - 0 0 1 1 *
 `@monthly` - Run once a month, midnight, first of month - 0 0 1 * *
 `@weekly` - Run once a week, midnight on Sun - 0 0 * * 0
 `@daily` - Run once a day, midnight - 0 0 * * *
 `@hourly` - Run once an hour, first minute - 0 * * * *
\Cron\FieldFactory $fieldFactory

Field factory to use

Returns

\Cron\CronExpression

isValidExpression()

isValidExpression(string  $expression) : boolean

Validate a CronExpression.

Parameters

string $expression

The CRON expression to validate.

Returns

boolean —

True if a valid CRON expression was passed. False if not.

__construct()

__construct(string  $expression, \Cron\FieldFactory  $fieldFactory) 

Parse a CRON expression

Parameters

string $expression

CRON expression (e.g. '8 ')

\Cron\FieldFactory $fieldFactory

Factory to create cron fields

setExpression()

setExpression(string  $value) : \Cron\CronExpression

Set or change the CRON expression

Parameters

string $value

CRON expression (e.g. 8 )

Throws

\InvalidArgumentException

if not a valid CRON expression

Returns

\Cron\CronExpression

setPart()

setPart(integer  $position, string  $value) : \Cron\CronExpression

Set part of the CRON expression

Parameters

integer $position

The position of the CRON expression to set

string $value

The value to set

Throws

\InvalidArgumentException

if the value is not valid for the part

Returns

\Cron\CronExpression

setMaxIterationCount()

setMaxIterationCount(integer  $maxIterationCount) : \Cron\CronExpression

Set max iteration count for searching next run dates

Parameters

integer $maxIterationCount

Max iteration count when searching for next run date

Returns

\Cron\CronExpression

getNextRunDate()

getNextRunDate(string|\DateTime  $currentTime = 'now', integer  $nth, boolean  $allowCurrentDate = false) : \DateTime

Get a next run date relative to the current date or a specific date

Parameters

string|\DateTime $currentTime

Relative calculation date

integer $nth

Number of matches to skip before returning a matching next run date. 0, the default, will return the current date and time if the next run date falls on the current date and time. Setting this value to 1 will skip the first match and go to the second match. Setting this value to 2 will skip the first 2 matches and so on.

boolean $allowCurrentDate

Set to TRUE to return the current date if it matches the cron expression.

Throws

\RuntimeException

on too many iterations

Returns

\DateTime

getPreviousRunDate()

getPreviousRunDate(string|\DateTime  $currentTime = 'now', integer  $nth, boolean  $allowCurrentDate = false) : \DateTime

Get a previous run date relative to the current date or a specific date

Parameters

string|\DateTime $currentTime

Relative calculation date

integer $nth

Number of matches to skip before returning

boolean $allowCurrentDate

Set to TRUE to return the current date if it matches the cron expression

Throws

\RuntimeException

on too many iterations

Returns

\DateTime

getMultipleRunDates()

getMultipleRunDates(integer  $total, string|\DateTime  $currentTime = 'now', boolean  $invert = false, boolean  $allowCurrentDate = false) : array

Get multiple run dates starting at the current date or a specific date

Parameters

integer $total

Set the total number of dates to calculate

string|\DateTime $currentTime

Relative calculation date

boolean $invert

Set to TRUE to retrieve previous dates

boolean $allowCurrentDate

Set to TRUE to return the current date if it matches the cron expression

Returns

array —

Returns an array of run dates

getExpression()

getExpression(string  $part = null) : string|null

Get all or part of the CRON expression

Parameters

string $part

Specify the part to retrieve or NULL to get the full cron schedule string.

Returns

string|null —

Returns the CRON expression, a part of the CRON expression, or NULL if the part was specified but not found

__toString()

__toString() : string

Helper method to output the full expression.

Returns

string —

Full CRON expression

isDue()

isDue(string|\DateTime  $currentTime = 'now') : boolean

Determine if the cron is due to run based on the current date or a specific date. This method assumes that the current number of seconds are irrelevant, and should be called once per minute.

Parameters

string|\DateTime $currentTime

Relative calculation date

Returns

boolean —

Returns TRUE if the cron is due to run or FALSE if not

getRunDate()

getRunDate(string|\DateTime  $currentTime = null, integer  $nth, boolean  $invert = false, boolean  $allowCurrentDate = false) : \DateTime

Get the next or previous run date of the expression relative to a date

Parameters

string|\DateTime $currentTime

Relative calculation date

integer $nth

Number of matches to skip before returning

boolean $invert

Set to TRUE to go backwards in time

boolean $allowCurrentDate

Set to TRUE to return the current date if it matches the cron expression

Throws

\RuntimeException

on too many iterations

Returns

\DateTime