phpcron

A small PHP CLI for poking at cron expressions.

• next — print the next N times the expression will fire
• explain — describe the schedule in plain English
• match — check whether a specific datetime matches (exit code = answer)

Zero Composer runtime dependencies. Ships as a ~80 MB Alpine + PHP 8.2 Docker image or runs directly from a checkout with PHP 8.2+.

Quick start (Docker)

docker build -t phpcron .

docker run --rm phpcron next "*/15 9-17 * * 1-5" --count 5 --from "2026-04-15 10:00"
docker run --rm phpcron explain "0 0 1 * *"
docker run --rm phpcron match "0 9 * * 1" "2026-04-13 09:00" && echo "fires!"

Quick start (local PHP)

git clone https://github.com/masaru87/phpcron.git
cd phpcron
./bin/phpcron next "*/15 9-17 * * 1-5"
./bin/phpcron explain "*/15 9-17 * * 1-5"
./bin/phpcron match "0 9 * * 1" "2026-04-13 09:00"; echo $?

No Composer install is needed for runtime — bin/phpcron uses a hand-rolled PSR-4 autoloader.

Commands

next <expr> [--count N] [--from "YYYY-MM-DD HH:MM"]

Prints the next N (default 5) instants that match, as UTC.

$ phpcron next "*/15 9-17 * * 1-5" --count 4 --from "2026-04-15 10:00"
next 4 run(s) for '*/15 9-17 * * 1-5' (UTC):
  2026-04-15 10:15 Wed
  2026-04-15 10:30 Wed
  2026-04-15 10:45 Wed
  2026-04-15 11:00 Wed

--from defaults to now. --count must be >= 1.

explain <expr>

$ phpcron explain "0 0 1 * *"
At 00:00, on day-of-month 1.

match <expr> <datetime>

Exit 0 if the datetime matches, 1 if not. Useful in scripts:

if phpcron match "0 9 * * 1-5" "$(date '+%Y-%m-%d %H:%M')"; then
    echo "it's a business hour"
fi

Supported syntax

Standard 5-field cron: minute hour dom month dow.

Token	Meaning	Example
*	every value	* * * * *
N	literal	30 14 * * *
N-M	inclusive range	9-17
*/S	every S from the field minimum	*/15
N-M/S	every S within a range	1-10/2
A,B,C	list (any mix of the above)	0,15,30,45

Day-of-week uses 0-6 where 0 is Sunday. 7 is accepted as a synonym for Sunday.

When both day-of-month and day-of-week are restricted, phpcron follows the classic Vixie-cron rule: a time matches if either field matches. This is why 0 0 1 * 1 fires on every 1st of the month and every Monday.

All times are UTC. phpcron is DST-agnostic by design — if you need local-zone cron semantics, convert before calling it.

Exit codes

Code	Meaning
0	success (or match returned true)
1	runtime error (invalid datetime, no match, unsatisfiable schedule)
2	usage error (bad argument, parse error)

Development

composer install
./vendor/bin/phpunit

41 tests cover parsing, matching, next-run iteration, explanation output, and CLI dispatch.

License

MIT. See LICENSE.

Links

• 📝 dev.to: https://dev.to/sendotltd/phpcron-a-tiny-php-cli-for-poking-at-cron-expressions-44be