Documentation

CronExpression
in package

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.

Tags
author

Michael Dowling mtdowling@gmail.com

link
http://en.wikipedia.org/wiki/Cron

Table of Contents

DAY  = 2
HOUR  = 1
MINUTE  = 0
MONTH  = 3
WEEKDAY  = 4
YEAR  = 5
$cronParts  : array<string|int, mixed>
$fieldFactory  : CronExpression_FieldFactory
$order  : array<string|int, mixed>
__construct()  : mixed
Parse a CRON expression
__toString()  : string
Helper method to output the full expression.
factory()  : CronExpression
Factory method to create a new CronExpression.
getExpression()  : string|null
Get all or part of the CRON expression
getMultipleRunDates()  : array<string|int, mixed>
Get multiple run dates starting at the current date or a specific date
getNextRunDate()  : DateTime
Get a next run date relative to the current date or a specific date
getPreviousRunDate()  : DateTime
Get a previous run date relative to the current date or a specific date
isDue()  : bool
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.
setExpression()  : CronExpression
Set or change the CRON expression
setPart()  : CronExpression
Set part of the CRON expression
getRunDate()  : DateTime
Get the next or previous run date of the expression relative to a date

Constants

Properties

$order

private static array<string|int, mixed> $order = array(self::YEAR, self::MONTH, self::DAY, self::WEEKDAY, self::HOUR, self::MINUTE)

Methods

__toString()

Helper method to output the full expression.

public __toString() : string
Return values
string

Full CRON expression

factory()

Factory method to create a new CronExpression.

public static factory(string $expression[, CronExpression_FieldFactory $fieldFactory = null ]) : CronExpression
Parameters
$expression : string

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 * * * *

$fieldFactory : CronExpression_FieldFactory = null

(optional) Field factory to use

Return values
CronExpression

getExpression()

Get all or part of the CRON expression

public getExpression([string $part = null ]) : string|null
Parameters
$part : string = null

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

Return values
string|null

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

getMultipleRunDates()

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

public getMultipleRunDates(int $total[, string|DateTime $currentTime = 'now' ][, bool $invert = false ][, bool $allowCurrentDate = false ]) : array<string|int, mixed>
Parameters
$total : int

Set the total number of dates to calculate

$currentTime : string|DateTime = 'now'

(optional) Relative calculation date

$invert : bool = false

(optional) Set to TRUE to retrieve previous dates

$allowCurrentDate : bool = false

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

Return values
array<string|int, mixed>

Returns an array of run dates

getNextRunDate()

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

public getNextRunDate([string|DateTime $currentTime = 'now' ], int $nth[, bool $allowCurrentDate = false ]) : DateTime
Parameters
$currentTime : string|DateTime = 'now'

(optional) Relative calculation date

$nth : int

(optional) 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.

$allowCurrentDate : bool = false

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

Tags
throws
RuntimeException

on too many iterations

Return values
DateTime

getPreviousRunDate()

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

public getPreviousRunDate([string|DateTime $currentTime = 'now' ], int $nth[, bool $allowCurrentDate = false ]) : DateTime
Parameters
$currentTime : string|DateTime = 'now'

(optional) Relative calculation date

$nth : int

(optional) Number of matches to skip before returning

$allowCurrentDate : bool = false

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

Tags
throws
RuntimeException

on too many iterations

see
CronExpression::getNextRunDate
Return values
DateTime

isDue()

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.

public isDue([string|DateTime $currentTime = 'now' ]) : bool
Parameters
$currentTime : string|DateTime = 'now'

(optional) Relative calculation date

Return values
bool

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

setExpression()

Set or change the CRON expression

public setExpression(string $value) : CronExpression
Parameters
$value : string

CRON expression (e.g. 8 * * * *)

Tags
throws
InvalidArgumentException

if not a valid CRON expression

Return values
CronExpression

setPart()

Set part of the CRON expression

public setPart(int $position, string $value) : CronExpression
Parameters
$position : int

The position of the CRON expression to set

$value : string

The value to set

Tags
throws
InvalidArgumentException

if the value is not valid for the part

Return values
CronExpression

getRunDate()

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

protected getRunDate([string|DateTime $currentTime = null ], int $nth[, bool $invert = false ][, bool $allowCurrentDate = false ]) : DateTime
Parameters
$currentTime : string|DateTime = null

(optional) Relative calculation date

$nth : int

(optional) Number of matches to skip before returning

$invert : bool = false

(optional) Set to TRUE to go backwards in time

$allowCurrentDate : bool = false

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

Tags
throws
RuntimeException

on too many iterations

Return values
DateTime

Search results