Cron Expression

Cron Expression is a PHP library that parses standard CRON expression syntax and answers three practical questions: is this expression due to run right now, what is its next run date, and what was its previous run date. It supports the full range of CRON syntax extensions found in real-world schedulers, including step ranges (*/12), lists (1,2,3), the W nearest-weekday flag, L for last day/weekday of the month, and # for the nth weekday of a month.

Originally forked from mtdowling/cron-expression, this is the actively maintained continuation used as the scheduling engine inside Laravel’s task scheduler and many other PHP frameworks and job runners. It has no runtime dependencies beyond PHP itself, making it a lightweight drop-in for any project that needs to evaluate or display cron-style schedules without shelling out to the system cron binary.

What You Get

• A CronExpression class with isDue(), getNextRunDate(), and getPreviousRunDate() methods
• Support for full CRON syntax including step ranges, lists, ranges, W (nearest weekday), L (last day/weekday), and # (nth weekday)
• Per-field parser classes (MinutesField, HoursField, DayOfMonthField, MonthField, DayOfWeekField) for granular validation
• The ability to skip N matching dates forward or backward to compute schedules far into the future or past
• Zero runtime dependencies beyond PHP 8.2+

Common Use Cases

• Powering a framework’s task scheduler (this library backs Laravel’s scheduler) to decide which jobs are due
• Displaying human-readable ‘next run’ times for scheduled jobs in an admin dashboard
• Validating user-supplied cron syntax in a UI before saving a scheduled task
• Building custom job queues or workers that need to evaluate cron-style schedules without relying on system cron

Under The Hood

Architecture: The library is organized around a central CronExpression class (src/Cron/CronExpression.php) that holds one FieldInterface implementation per cron field — MinutesField, HoursField, DayOfMonthField, MonthField, DayOfWeekField — each extending a shared AbstractField that implements range/step/list parsing once and lets subclasses override only field-specific validation (e.g. weekday numbering, month names). A FieldFactory wires up the field instances, keeping the expression parser decoupled from field-specific logic.

Tech Stack: Pure PHP 8.2+ with no runtime dependencies; dev tooling is PHPUnit for tests and PHPStan (level enforced via phpstan.neon) for static analysis, both run through Composer scripts (composer test, composer phpstan).

Code Quality: The tests/Cron/ directory mirrors src/Cron/ with a dedicated test class per field plus expression-level tests covering edge cases like DST transitions, leap years, and L/W/# modifiers; CI runs both the test suite and static analysis on every push, and the AbstractField base class enforces consistent validation logic rather than duplicating range-parsing per field.

API Design: The public API is intentionally small — construct a CronExpression from a schedule string, then call isDue(), getNextRunDate(), or getPreviousRunDate(), each accepting an optional reference time and skip count. Field names and method names map directly to cron terminology, so developers already familiar with crontab syntax need almost no ramp-up time.