philiprehberger/cron-expression-builder

Fluent cron expression builder with human-readable methods

v1.0.2 2026-03-17 20:06 UTC

Requires

• php: ^8.2

Requires (Dev)

• laravel/pint: ^1.0
• phpstan/phpstan: ^1.12|^2.0
• phpunit/phpunit: ^11.0

MIT

• Philip Rehberger

• time
• cron
• schedule
• builder
• expression

README

Fluent cron expression builder with human-readable methods. Framework-agnostic, zero dependencies.

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 *

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 * * *

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
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

License

MIT