APPNETOS is under active development This website and its documentation are being prepared for public launch. Content and features may change.
Select Theme
Loading

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.

Cron expression parsing and matching flow
Parsing and matching are separate from scheduling and job execution.
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 DateTime and the timezone used by the caller.
  • The matcher works at minute granularity. Seconds do not appear in the five-field expression.

For job execution architecture, see Worker and Cmd.

Next Steps

Previous

Utilities

Explore Utilities

Next

QrCode

Explore QrCode