Cron

Register per-minute crons by module and name, run them one by one or by name, and log each run's start, end, output and any error. Also runs a callback within a bounded time window, and simulates second-resolution crons across a run.

This page is a pure reference. For how the framework fits together, see the Guide.

Classes

Cron - run registered crons, and run a callback within a time window.
CronCommand - the command routing for the cron command.
CronConfig - register the per-minute crons a module provides.
CronLogData - immutable record of a single cron run.
CronLogDatabase - write and read cron run log rows.
CronSimulate - simulate second-resolution crons over a fixed run.

Cron

Runs the crons registered through CronConfig, and provides helpers to run a callback for up to, or for at least, a given number of seconds.

Functions

Run RunCallback RunForAtLeast RunForUpTo

Run

Cron::Run(): void

Register the cron command with its minute and named subcommands, then start the command server. The minute subcommand launches each registered cron as a separate named run; the named subcommand runs a single cron by its name.

Returns void

RunCallback

Cron::RunCallback(string $moduleName, string $cronName, callable $callback): void

Run a single cron callback, logging its start and end. Output is captured and any thrown error is recorded as the run's error message.

Name	Type	Description
`$moduleName`	`string`	The module the cron belongs to.
`$cronName`	`string`	The name of the cron.
`$callback`	`callable`	The work to run.

Returns void

RunForAtLeast

Cron::RunForAtLeast(float $secondsToRun, callable $callback): void

Run the callback once, then sleep for any remaining time so the call takes at least the given number of seconds.

Name	Type	Description
`$secondsToRun`	`float`	The least number of seconds the call should take.
`$callback`	`callable`	The work to run once.

Returns void

RunForUpTo

Cron::RunForUpTo(float $secondsToRun, callable $callback): void

Call the callback repeatedly until it returns a falsey value or the given number of seconds has elapsed, whichever comes first.

Name	Type	Description
`$secondsToRun`	`float`	The most number of seconds to keep calling for.
`$callback`	`callable`	Called each iteration; return a falsey value to stop early.

Returns void

CronCommand

The command routing for the cron command, with a minute subcommand that starts every registered cron and a named subcommand that runs one cron by name.

Functions

Route

CronCommand::Route(): void

Define the cron command's subcommands. The minute subcommand starts each registered cron as its own named process; the named subcommand takes a cron name argument and runs that cron's callback.

Returns void

CronConfig

Properties

Property	Type	Description
`CronConfig::$crons`	`array`	The registered crons, keyed by cron name; each holds the module name and callback.

Functions

Minute

CronConfig::Minute(string $moduleName, string $cronName, callable $callback): void

Name	Type	Description
`$moduleName`	`string`	The module the cron belongs to.
`$cronName`	`string`	The name of the cron, used as its key.
`$callback`	`callable`	The work to run each minute.

Returns void

CronLogData

Immutable record of a single cron run. Fields and constructor only.

Properties

Property	Type	Description
`$data->id`	`int`	The log row id (readonly).
`$data->moduleName`	`string`	The module the cron belongs to (readonly).
`$data->cronName`	`string`	The name of the cron (readonly).
`$data->startTime`	`int`	The start time as a Unix timestamp (readonly).
`$data->endTime`	`int\|null`	The end time as a Unix timestamp, or null while running (readonly).
`$data->output`	`string\|null`	The captured output, or null (readonly).
`$data->hasError`	`bool`	Whether the run recorded an error (readonly).
`$data->errorMsg`	`string\|null`	The error message, or null (readonly).

__construct

new CronLogData(int $id = 0, string $moduleName = '', string $cronName = '', int $startTime = 0, int|null $endTime = null, string|null $output = null, bool $hasError = false, string|null $errorMsg = null)

Create a cron log record from its fields.

Name	Type	Description
`$id`	`int`	The log row id.
`$moduleName`	`string`	The module the cron belongs to.
`$cronName`	`string`	The name of the cron.
`$startTime`	`int`	The start time as a Unix timestamp.
`$endTime`	`int\|null`	The end time as a Unix timestamp, or null.
`$output`	`string\|null`	The captured output, or null.
`$hasError`	`bool`	Whether the run recorded an error.
`$errorMsg`	`string\|null`	The error message, or null.

Returns CronLogData

CronLogDatabase

Write and read the cron run log rows, recording a run's start and then its end with output and any error.

Functions

End fromRow Start

End

CronLogDatabase::End(int $cronLogId, string|null $output, string|null $optionalErrorMessage): void

Complete a log row, setting its end timestamp, captured output, and error state and message.

Name	Type	Description
`$cronLogId`	`int`	The id of the log row to complete.
`$output`	`string\|null`	The captured output, or null.
`$optionalErrorMessage`	`string\|null`	The error message, or null when there was no error.

Returns void

fromRow

CronLogDatabase::fromRow(stdClass $row): CronLogData

Build a CronLogData from a database row.

Name	Type	Description
`$row`	`stdClass`	The database row to convert.

Returns CronLogData The cron run record.

Start

CronLogDatabase::Start(string $moduleName, string $cronName): int

Insert a new log row for a cron run, recording its module name, cron name, date and start timestamp.

Name	Type	Description
`$moduleName`	`string`	The module the cron belongs to.
`$cronName`	`string`	The name of the cron.

Returns int The id of the new log row.

CronSimulate

Run for a fixed number of seconds, calling a per-second callback at the correct times, so second-resolution crons can be simulated within a single process. Individual crons are defined with a regularity and an offset so they can be spread across the window.

Constants

Constant	Value	Description
`CronSimulate::PROCESS_SKIP_NONE`	`0`	Run every second regardless of how long callbacks take; a slow callback runs the next immediately.
`CronSimulate::PROCESS_SKIP_SECONDS`	`1`	When a callback runs long, move to the next second; seconds may be skipped entirely.
`CronSimulate::PROCESS_SKIP_OVERRUN`	`2`	Like skip none, but stop once the run time has passed and skip the remaining crons.
`CronSimulate::PROCESS_SKIP__MAX`	`2`	The highest valid skip mode value.

Properties

Property	Type	Description
`CronSimulate::$currentTimestamp`	`int`	The timestamp of the second currently being processed.

Functions

Cron Process processSeconds

Cron

CronSimulate::Cron(int $regularitySeconds, int $offsetSeconds, callable $callback): void

Call the callback when the current timestamp matches the offset within the regularity, giving a cron that fires every regularity seconds at a chosen point in that cycle.

Name	Type	Description
`$regularitySeconds`	`int`	How many seconds between calls.
`$offsetSeconds`	`int`	The point within the regularity at which to fire, from 0 to regularity minus one.
`$callback`	`callable`	The work to run when the cron fires.

Returns void

Process

CronSimulate::Process(int $startTimestamp, int $runForSeconds, int $skipMode, callable $callback): void

Run for the given number of seconds, calling the callback once per second with the current timestamp set, sleeping in real time to stay on schedule. The skip mode decides what happens when a callback runs longer than a second.

Name	Type	Description
`$startTimestamp`	`int`	The timestamp of the first second, for example the current time rounded to the minute.
`$runForSeconds`	`int`	How many seconds to run for, for example 60.
`$skipMode`	`int`	One of the CronSimulate PROCESS_SKIP constants.
`$callback`	`callable`	Called each second; it calls CronSimulate::Cron for each simulated cron.

Returns void

processSeconds

CronSimulate::processSeconds(int $startTimestamp, int $runForSeconds, bool $stopOnTime, bool $skipSecondsIfLate, callable $callback): void

Loop over each second of the run, sleeping while ahead of schedule and calling the callback with the current timestamp set, according to the given behaviour flags.

Name	Type	Description
`$startTimestamp`	`int`	The timestamp of the first second.
`$runForSeconds`	`int`	How many seconds to run for.
`$stopOnTime`	`bool`	True to stop once the real elapsed time exceeds the run time.
`$skipSecondsIfLate`	`bool`	True to call the callback only while on or ahead of schedule, skipping late seconds.
`$callback`	`callable`	Called each second with the current timestamp set.

Returns void