Cron
Parse, validate, and match standard five-field cron expressions against a PHP DateTime.
The APPNETOS Cron utility determines whether a schedule is due. It does not register system cron jobs, run a background timer, enqueue workers, or execute callbacks.
Architecture and responsibilities
Core\Cron is a shared facade that lazily resolves a shared parser and matcher from the
APPNETOS Registry. Parsing produces an expression containing five validated field objects. Matching
compares these fields to a supplied point in time.
| Component | Responsibility |
|---|---|
Core\Cron |
Shared facade; init(), parse(), isDue(),
accessors.
|
Core\Cron\Parser |
Validate and expand a five-field expression. |
Core\Cron\Expression |
Hold minute, hour, day-of-month, month and day-of-week fields. |
Core\Cron\Field |
Hold field name, bounds, normalized values and wildcard state; test values. |
Core\Cron\Matcher |
Compare an expression with DateTime. |
Core\Cron\Exception\CronException |
Describe invalid expressions using named factory methods. |
Quick start
use Core\Cron;
use Core\Registry;
$cron = Registry::get(Cron::class);
if ($cron->isDue('*/15 8-18 * * 1-5', new DateTime('now'))) {
// Application-specific action: enqueue a worker, run a command, etc.
}
When the second argument is omitted, isDue() creates a new DateTime(). The
active PHP default timezone is used in that case. For predictable schedules, supply an explicitly
configured timezone.
$timezone = new DateTimeZone('Europe/Berlin');
$at = new DateTime('2026-11-09 09:00:00', $timezone);
$isDue = $cron->isDue('0 9 * * 1-5', $at);
Expression format
┌──────── minute (0–59)
│ ┌────── hour (0–23)
│ │ ┌──── day of month (1–31)
│ │ │ ┌── month (1–12)
│ │ │ │ ┌ day of week (0–7, Sunday = 0 or 7)
* * * * *
The parser accepts five whitespace-separated fields. Supported constructs include wildcard
(*), numeric values, comma-separated lists, inclusive ranges, steps, and range steps.
| Expression | Interpretation |
|---|---|
* * * * * |
Every minute |
30 8 * * * |
Every day at 08:30 |
0 8,12,18 * * * |
At 08:00, 12:00, and 18:00 |
0 9-17 * * * |
Every hour from 09:00 through 17:00 |
*/15 * * * * |
Every 15 minutes |
0 8-18/2 * * * |
Every two hours from 08:00 through 18:00 |
0 9 * * 1-5 |
Weekdays at 09:00 |
Values are validated against field-specific bounds, deduplicated and sorted. Day-of-week value
7 represents Sunday, as does 0.
Day matching semantics
Minute, hour, and month must always match. The day fields follow traditional cron behavior:
- If both day-of-month and day-of-week are wildcards, the day condition passes.
- If only one is restricted, that restricted field must match.
- If both are restricted, either field may match (logical OR).
For example, 0 9 1 * 1 matches at 09:00 on the first day of a month or on a
Monday.
It does not require both conditions simultaneously.
Public API Reference
Core\Cron
Class & Registry
Class:
Core\Cron
Extends:
Core\Cron\Base
use Core\Cron;
use Core\Registry;
$cron = Registry::get(Cron::class);
| Method | Description |
|---|---|
init() |
Initialize parser and matcher once. |
parse(string $expression) |
Validate and parse a schedule. |
isDue(string $expression, ?DateTime $dateTime = null) |
Check a schedule at a point in time. |
getParser() |
Access the parser if initialized. |
getMatcher() |
Access the matcher if initialized. |
isInitialized() |
Check initialization state. |
Inspecting a parsed expression
$expression = $cron->parse('*/15 8-18 * * 1-5');
$minute = $expression->getMinute();
$allowedMinutes = $minute->getValues();
$wildcard = $minute->isWildcard();
$fields = $expression->getFields();
// Individual fields also expose getName(), getMinimum(),
// getMaximum(), matches(int), and isInRange(int).
The expression exposes getMinute(), getHour(), getDayOfMonth(),
getMonth(), getDayOfWeek(), and getFields(). The matcher
exposes
matches(Expression $expression, DateTime $dateTime).
Validation and exceptions
Invalid expressions raise Core\Cron\Exception\CronException, a specialized APPNETOS
exception. Its named factories describe the failure rather than requiring callers to construct raw
error
messages.
use Core\Cron\Exception\CronException;
try {
$cron->parse('*/0 * * * *');
} catch (CronException $exception) {
// Report the validation failure or return a safe application response.
}
Available factory names include expressionEmpty(), invalidFieldCount(),
fieldEmpty(),
wildcardInList(), emptyListValue(), fieldWithoutValues(),
invalidStepExpression(),
invalidStepValue(), invalidFieldValue(),
invalidRangeExpression(),
invalidRangeOrder(), and fieldValueOutOfRange().
Scheduling integration and operational notes
isDue() is a predicate, not a scheduler. Invoke it from an external scheduler, a CLI
command, or application-controlled scheduling logic. Integrate with APPNETOS Workers if execution
should
be queued or retried.
- Calling
isDue()repeatedly during the same matching minute can trigger application code repeatedly. Implement deduplication or locking in the calling scheduler. - The utility evaluates the supplied
DateTime; it does not itself persist last-run timestamps, compensate for missed runs, or handle distributed locking. - Daylight-saving transitions and timezone changes are governed by PHP
DateTimeand the timezone used by the caller. - The matcher works at minute granularity. Seconds do not appear in the five-field expression.