CronFrequency
in package
Schedule of one cron job: every N minutes, daily, weekly, monthly or manual only. Pure value object — "is the job due?" depends only on the schedule, the time of the last run and "now", so it is unit-testable without a clock.
Text form (stored in the DB and in CronJob):
every:15 · daily:03:30 · weekly:1@03:30 (1 = Monday … 7 = Sunday) · monthly:31@03:30 · manual.
Daily/weekly/monthly use the "latest scheduled slot" rule: the job is due when it has not run
since the most recent slot that is not in the future. A scheduler that was down therefore runs
the job once after it returns (not once per missed slot), and a call that happens a minute late
still hits the slot. Times are wall-clock times in the time zone of the $now passed in
(the application time zone) — a slot that does not exist on the spring DST change moves to the
next valid time, a repeated one on the autumn change is taken once.
Interval is measured from the last run with a small tolerance, because the scheduler itself is called by a hosting cron whose ticks never land on exactly the same second.
Table of Contents
Constants
- INTERVAL_TOLERANCE_SECONDS : int = 30
- Scheduler ticks jitter; an interval job is due this many seconds before its time.
- MAX_INTERVAL_MINUTES : int = 1440
- Longest allowed interval (24 h) — longer periods are daily/weekly/monthly.
Properties
Methods
- daily() : self
- interval() : self
- isDue() : bool
- Is the job due at `$now`, when it last ran at `$lastRun` (`null` = never)? A never-run job is due at once (except `manual`, which is never due).
- latestSlot() : DateTimeImmutable|null
- The most recent scheduled moment that is not after `$now`; `null` for interval and manual.
- manual() : self
- monthly() : self
- A day missing in a short month (31st in April) falls on the last day of that month.
- parse() : self|null
- `null` for text that is not a valid frequency.
- toString() : string
- weekly() : self
- __construct() : mixed
- assertTime() : void
- monthSlot() : DateTimeImmutable
Constants
INTERVAL_TOLERANCE_SECONDS
Scheduler ticks jitter; an interval job is due this many seconds before its time.
public
int
INTERVAL_TOLERANCE_SECONDS
= 30
MAX_INTERVAL_MINUTES
Longest allowed interval (24 h) — longer periods are daily/weekly/monthly.
public
int
MAX_INTERVAL_MINUTES
= 1440
Properties
$day read-only
public
int
$day
= 0
$hour read-only
public
int
$hour
= 0
$minute read-only
public
int
$minute
= 0
$minutes read-only
public
int
$minutes
= 0
$type read-only
public
CronFrequencyType
$type
$weekday read-only
public
int
$weekday
= 0
Methods
daily()
public
static daily(int $hour, int $minute) : self
Parameters
- $hour : int
- $minute : int
Return values
selfinterval()
public
static interval(int $minutes) : self
Parameters
- $minutes : int
Return values
selfisDue()
Is the job due at `$now`, when it last ran at `$lastRun` (`null` = never)? A never-run job is due at once (except `manual`, which is never due).
public
isDue(DateTimeInterface|null $lastRun, DateTimeInterface $now) : bool
Parameters
- $lastRun : DateTimeInterface|null
- $now : DateTimeInterface
Return values
boollatestSlot()
The most recent scheduled moment that is not after `$now`; `null` for interval and manual.
public
latestSlot(DateTimeInterface $now) : DateTimeImmutable|null
Parameters
- $now : DateTimeInterface
Return values
DateTimeImmutable|nullmanual()
public
static manual() : self
Return values
selfmonthly()
A day missing in a short month (31st in April) falls on the last day of that month.
public
static monthly(int $day, int $hour, int $minute) : self
Parameters
- $day : int
- $hour : int
- $minute : int
Return values
selfparse()
`null` for text that is not a valid frequency.
public
static parse(string $text) : self|null
Parameters
- $text : string
Return values
self|nulltoString()
public
toString() : string
Return values
stringweekly()
public
static weekly(int $weekday, int $hour, int $minute) : self
Parameters
- $weekday : int
-
ISO weekday, 1 = Monday … 7 = Sunday
- $hour : int
- $minute : int
Return values
self__construct()
private
__construct(CronFrequencyType $type[, int $minutes = 0 ][, int $hour = 0 ][, int $minute = 0 ][, int $weekday = 0 ][, int $day = 0 ]) : mixed
Parameters
- $type : CronFrequencyType
- $minutes : int = 0
- $hour : int = 0
- $minute : int = 0
- $weekday : int = 0
- $day : int = 0
assertTime()
private
static assertTime(int $hour, int $minute) : void
Parameters
- $hour : int
- $minute : int
monthSlot()
private
monthSlot(DateTimeImmutable $reference) : DateTimeImmutable
Parameters
- $reference : DateTimeImmutable