cron
Table of Contents
Functions
- cronFieldValues() : array<int, int>|null
- Expands one field of a cron expression into the values it matches.
- cronScheduleGap() : int|null
- Measures the longest time a cron expression can leave between two runs.
Functions
cronFieldValues()
Expands one field of a cron expression into the values it matches.
cronFieldValues(string $field, int $min, int $max) : array<int, int>|null
Reads what a hand-written crontab holds: a star, a number, a range a-b, a step written with a
slash after a star or a range (*, 0-12 followed by / and the step), and any comma-separated
mix of those. A reader that handles only the first two silently misreads a six-hourly schedule
as a daily one.
Returns null rather than guessing: a value out of [$min, $max], a range written
backwards, a zero step, a name (mon, jan) or a preset (@daily) give null. A field that
cannot be read is a schedule whose promise is unknown, and a caller should say so rather than
take it for any particular schedule.
Parameters
- $field : string
-
The field, e.g.
*,3,1-5,0,30, or a step over a star or a range. - $min : int
-
The lowest legal value for this field (0 for minutes and hours, 1 for days of the month and months, 0 for days of the week).
- $max : int
-
The highest legal value for this field (59, 23, 31, 12, and 7 for days of the week, where both 0 and 7 are Sunday).
Tags
Return values
array<int, int>|null —The matching values, ascending and each once; null when the field cannot be read.
cronScheduleGap()
Measures the longest time a cron expression can leave between two runs.
cronScheduleGap(string $expression) : int|null
The number a "this job has not run for too long" check needs, and deliberately the longest
gap rather than the average or the nominal period. 30 2 * * 1-5 runs five times a week, which
averages to 33 hours; what matters is that it leaves 72 hours across the weekend, because a
shorter threshold would alert every Sunday on a job behaving exactly as configured — and an
alert that cries on a working setup is an alert people turn off.
Computed by laying out one cycle rather than by recognising presets: every run in a day, a week or a month — depending on which fields are restricted — and the widest interval between two consecutive runs, wrapping around the end of the cycle. A restriction on the day of the month is read on a 31-day cycle: the pessimistic reading, since a job on the 31st skips the months that have none.
Returns null for a schedule it will not guess at:
- a field cronFieldValues() cannot read, or not exactly five fields;
- a month restriction — a yearly schedule, whose gap depends on the year;
- a restricted day of the month and a restricted day of the week: cron then runs when either matches, which is not a cycle this measures.
Parameters
- $expression : string
-
The five standard fields: minute, hour, day of month, month, day of week.
Tags
Return values
int|null —The longest interval between two runs, in seconds; null when it is not known.