PHP Cron Expression Builder

Fluent cron expression builder with human-readable methods.

Requirements

• PHP 8.2+

Installation

composer require philiprehberger/cron-expression-builder

Usage

Static Shortcuts

Use the Cron class for common schedules:

use PhilipRehberger\CronBuilder\Cron;

Cron::everyMinute();          // * * * * *
Cron::everyFiveMinutes();     // */5 * * * *
Cron::everyTenMinutes();      // */10 * * * *
Cron::everyFifteenMinutes();  // */15 * * * *
Cron::everyThirtyMinutes();   // */30 * * * *
Cron::hourly();               // 0 * * * *
Cron::hourlyAt(30);           // 30 * * * *
Cron::daily();                // 0 0 * * *
Cron::dailyAt('14:30');       // 30 14 * * *
Cron::weekly();               // 0 0 * * 0
Cron::weeklyOn(1, '09:00');   // 0 9 * * 1
Cron::monthly();              // 0 0 1 * *
Cron::monthlyOn(15, '08:00'); // 0 8 15 * *
Cron::yearly();               // 0 0 1 1 *

Preset Intervals

Use builder presets for common intervals:

use PhilipRehberger\CronBuilder\Cron;

Cron::custom()->everyQuarterHour()->build();                   // */15 * * * *
Cron::custom()->everyHalfHour()->build();                      // */30 * * * *
Cron::custom()->everyQuarterHour()->hour('9-17')->build();     // */15 9-17 * * *
Cron::custom()->weeklyOnDay('Monday')->minute('0')->hour('9')->build(); // 0 9 * * 1

Custom Builder

Build complex expressions with the fluent builder:

use PhilipRehberger\CronBuilder\Cron;

$expression = Cron::custom()
    ->minute('*/10')
    ->hour('9-17')
    ->dayOfWeek('1-5')
    ->build();

// */10 9-17 * * 1-5

The builder implements Stringable, so you can use it directly in string contexts:

echo Cron::custom()->minute('0')->hour('*/2'); // 0 */2 * * *

Next Run Date

Calculate the next execution time from a cron expression:

use PhilipRehberger\CronBuilder\CronExpression;

$expr = new CronExpression('0 9 * * 1');
$next = $expr->nextRunDate(); // Next Monday at 09:00

// With a specific starting datetime
$from = new \DateTimeImmutable('2026-03-22 10:00:00');
$next = $expr->nextRunDate($from); // 2026-03-23 09:00

Next N Run Dates

Calculate multiple upcoming execution times:

use PhilipRehberger\CronBuilder\CronExpression;
use PhilipRehberger\CronBuilder\CronScheduler;

// Via static method
$runs = CronScheduler::nextRuns('0 9 * * *', 5);

// Via CronExpression convenience method
$expr = new CronExpression('*/5 * * * *');
$runs = $expr->nextRuns(3, new \DateTimeImmutable('2026-03-22 10:00:00'));
// [2026-03-22 10:05, 2026-03-22 10:10, 2026-03-22 10:15]

Overlap Detection

Check if cron schedules produce overlapping execution times:

use PhilipRehberger\CronBuilder\CronScheduler;

// Check two expressions within a 24-hour window
CronScheduler::overlaps('0 9 * * *', '0 9 * * *'); // true
CronScheduler::overlaps('0 9 * * *', '0 14 * * *'); // false

// Find all overlaps among multiple expressions
$overlaps = CronScheduler::findOverlaps([
    'backup' => '0 2 * * *',
    'cleanup' => '0 2 * * *',
    'report' => '0 9 * * *',
], 24);
// [['expressions' => ['backup', 'cleanup'], 'time' => DateTimeImmutable]]

Interval Analysis

Analyze the timing intervals between cron runs:

use PhilipRehberger\CronBuilder\CronInterval;

CronInterval::averageInterval('*/5 * * * *'); // 300.0 (seconds)
CronInterval::minInterval('0 0 * * *');       // 86400.0 (seconds)
CronInterval::maxInterval('0 0 * * *');       // 86400.0 (seconds)

Validator

Validate cron expression syntax:

use PhilipRehberger\CronBuilder\CronValidator;

CronValidator::isValid('*/5 * * * *');   // true
CronValidator::isValid('60 * * * *');    // false
CronValidator::isValid('invalid');       // false

Describer

Get human-readable descriptions:

use PhilipRehberger\CronBuilder\CronDescriber;

CronDescriber::describe('* * * * *');      // "Every minute"
CronDescriber::describe('0 * * * *');      // "Every hour"
CronDescriber::describe('0 0 * * *');      // "Every day at midnight"
CronDescriber::describe('*/5 * * * *');    // "Every 5 minutes"
CronDescriber::describe('30 14 * * *');    // "Every day at 14:30"
CronDescriber::describe('0 0 * * 0');      // "Every Sunday at midnight"
CronDescriber::describe('0 0 1 * *');      // "First day of every month at midnight"
CronDescriber::describe('0 0 1 1 *');      // "Every year on January 1st at midnight"

API

Method	Returns	Description
Cron::everyMinute()	string	Every minute (* * * * *)
Cron::everyFiveMinutes()	string	Every 5 minutes (*/5 * * * *)
Cron::everyTenMinutes()	string	Every 10 minutes (*/10 * * * *)
Cron::everyFifteenMinutes()	string	Every 15 minutes (*/15 * * * *)
Cron::everyThirtyMinutes()	string	Every 30 minutes (*/30 * * * *)
Cron::hourly()	string	Every hour at :00 (0 * * * *)
Cron::hourlyAt(int $minute)	string	Every hour at given minute
Cron::daily()	string	Every day at midnight (0 0 * * *)
Cron::dailyAt(string $time)	string	Every day at HH:MM
Cron::weekly()	string	Every Sunday at midnight
Cron::weeklyOn(int $day, string $time)	string	Weekly on given day at time
Cron::monthly()	string	First of month at midnight
Cron::monthlyOn(int $day, string $time)	string	Monthly on given day at time
Cron::yearly()	string	January 1st at midnight
Cron::custom()	CronBuilder	Start fluent builder
CronBuilder::everyQuarterHour()	self	Set minute to */15
CronBuilder::everyHalfHour()	self	Set minute to */30
CronBuilder::weeklyOnDay(string $dayName)	self	Set day of week by English name
CronExpression::nextRunDate(?DateTimeInterface $from)	DateTimeImmutable	Next execution time
CronExpression::nextRuns(int $count, ?DateTimeInterface $from)	array	Next N execution times
CronScheduler::nextRuns(string|CronExpression $expr, int $count, ?DateTimeInterface $from)	array	Next N run dates
CronScheduler::overlaps(string|CronExpression $a, string|CronExpression $b, int $windowHours, ?DateTimeInterface $from)	bool	Check if two schedules overlap
CronScheduler::findOverlaps(array $expressions, int $windowHours, ?DateTimeInterface $from)	array	Find all overlapping pairs
CronInterval::averageInterval(string|CronExpression $expr, int $sampleSize, ?DateTimeInterface $from)	float	Average seconds between runs
CronInterval::minInterval(string|CronExpression $expr, int $sampleSize, ?DateTimeInterface $from)	float	Minimum seconds between runs
CronInterval::maxInterval(string|CronExpression $expr, int $sampleSize, ?DateTimeInterface $from)	float	Maximum seconds between runs
CronValidator::isValid(string $expr)	bool	Validate cron syntax
CronDescriber::describe(string $expr)	string	Human-readable description

Development

composer install
vendor/bin/phpunit
vendor/bin/pint --test
vendor/bin/phpstan analyse

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT