README

Cron expression generator is a beautiful tool for PHP applications. Of course, the primary feature of this package is the ability to generate cron expressions.

Features

Cron expressions generator
Pre built expressions
Custom expressions
Well documented
Well tested
Compatible with Laravel

Requirements

PHP 8.0 and above

Installation

You can install the package via composer:

composer require butschster/cron-expression-generator

That's it!

Usage

Creates a new generator

use Butschster\CronExpression\Generator;
use Cron\CronExpression;

$generator = new Generator();
// or
$generator = new Generator(new CronExpression('* * * * *'));
// or
$generator = Generator::create();
// or
$generator = Generator::create(new CronExpression('* * * * *'));

Gets expression object

$expression = $generator->getExpression(); // \Cron\CronExpression

Converts expression to a string

echo $generator->toExpression(); // * * * * *

echo (string) $generator; // * * * * *

echo (string) $generator->getExpression(); // * * * * *

echo $generator->getExpression()->getExpression(); // * * * * *

Sets specific cron expression

echo $generator->cron('* */3 * * *'); // * */3 * * *

echo $generator->cron('* */3 * * *')->everyTwoMinutes(); // */2 */3 * * *

Manipulate minutes

// Every minute
echo $generator->everyMinute(); // * * * * *

// Every even minute
echo $generator->everyEvenMinute(); // */2 * * * *

// Every two minutes
echo $generator->everyTwoMinutes(); // */2 * * * *

// Every three minutes
echo $generator->everyThreeMinutes(); // */3 * * * *

// Every four minutes
echo $generator->everyFourMinutes(); // */4 * * * *

// Every five minutes
echo $generator->everyFiveMinutes(); // */5 * * * *

// Every ten minutes
echo $generator->everyTenMinutes(); // */10 * * * *

// Every fifteen minutes
echo $generator->everyFifteenMinutes(); // */15 * * * *

// Every 00 and 30 minutes
echo $generator->everyThirtyMinutes(); // 0,30 * * * *

// Every minute
echo $generator->set(new \Butschster\CronExpression\Parts\Minutes\EveryMinute()); // * * * * *
echo $generator->set(new \Butschster\CronExpression\Parts\Minutes\EveryMinute(2)); // * */2 * * *

// Specific minutes
echo $generator->set(new \Butschster\CronExpression\Parts\Minutes\SpecificMinutes(2, 3, 10)); // * 2,3,10 * * *

// Between minutes
echo $generator->set(new \Butschster\CronExpression\Parts\Minutes\BetweenMinutes(0, 30)); // * 0-30 * * *

Manipulate hours

// Every hour at 00 minutes
echo $generator->hourly(); // 0 * * * *

// Every hour at 15 minutes
echo $generator->hourlyAt(15); // 15 * * * *

// Every hour at 15, 30, 45 minutes
echo $generator->hourlyAt(15, 30, 45); // 15,30,45 * * * *

// Every two hours
echo $generator->everyTwoHours(); // 0 */2 * * *

// Every three hours
echo $generator->everyThreeHours(); // 0 */3 * * *

// Every four hours
echo $generator->everyFourHours(); // 0 */4 * * *

// Every six hours
echo $generator->everySixHours(); // 0 */6 * * *

// Every 1, 2, 3 hours
echo $generator->set(new \Butschster\CronExpression\Parts\Hours\SpecificHours(1, 2, 3)); // * 1,2,3 * * *

// Every three hours
echo $generator->set(new \Butschster\CronExpression\Parts\Hours\EveryHour()); // * * * * *
echo $generator->set(new \Butschster\CronExpression\Parts\Hours\EveryHour(3)); // * */3 * * *

// Between hours
echo $generator->set(new \Butschster\CronExpression\Parts\Hours\BetweenHours(0, 12)); // * 0-12 * * *

Manipulate days

// Every day at 00:00
echo $generator->daily(); // 0 0 * * *

// Every day at 01:00
echo $generator->daily(1); // 0 1 * * *

// Every day at 03:00, 15:00, 23:00
echo $generator->daily(3, 15, 23); // 0 3,15,23 * * *

// Every day at 13:00
echo $generator->dailyAt(13); // 0 13 * * *

// Every day at 13:25
echo $generator->dailyAt(13, 25); // 25 13 * * *

// Every day at 03:00, 15:00
echo $generator->twiceDaily(3, 15); // 0 3,15 * * *

// Every day at 03:05, 15:05
echo $generator->twiceDailyAt(3, 15, 5); // 5 3,15 * * *

// Every month on the last day at 00:00
echo $generator->lastDayOfMonth(); // 0 0 L * *

// Every month on the last day at 12:00
echo $generator->lastDayOfMonth(12); // 0 12 L * *

// Every month on the last day at 12:30
echo $generator->lastDayOfMonth(12, 30); // 30 12 L * *

// Every month on the last weekday at 00:00
echo $generator->lastWeekdayOfMonth(); // 0 0 LW * *

// Every month on the last weekday at 12:00
echo $generator->lastWeekdayOfMonth(12); // 0 12 LW * *

// Every month on the last weekday at 12:30
echo $generator->lastWeekdayOfMonth(12, 30); // 30 12 LW * *

// Every 1, 2, 3 days
echo $generator->set(new \Butschster\CronExpression\Parts\Days\SpecificDays(1, 2, 3)); // * * 1,2,3 * *

echo $generator->set(new \Butschster\CronExpression\Parts\Days\EveryDay()); // * * * * *

// Every three days
echo $generator->set(new \Butschster\CronExpression\Parts\Days\EveryDay(3)); // * * */3 * *

// Between days
echo $generator->set(new \Butschster\CronExpression\Parts\Days\BetweenDays(0, 12)); // * * 0-12 * *

// Last day of month
echo $generator->set(new \Butschster\CronExpression\Parts\Days\LastDayOfMonth()); // * * L * *

Manipulate days of week

// Every week on monday
echo $generator->weekly(); // 0 0 * * 0

// Every week on monday and thursday
echo $generator->weekly(Generator::MONDAY, Generator::THURSDAY); // 0 0 * * 1,4

// Every week on weekdays
echo $generator->daily()->weekdays(); // 0 0 * * 1-5

// Every week on weekends
echo $generator->daily()->weekends(); // 0 0 * * 6,0

// Every monday
echo $generator->daily()->mondays(); // 0 0 * * 1
// or
echo $generator->weeklyOnMonday();
// or
echo $generator->weeklyOnMonday(8, 6); // 6 8 * * 1

// Every tuesday
echo $generator->daily()->tuesdays(); // 0 0 * * 2
// or
echo $generator->weeklyOnTuesday();

// Every wednesday
echo $generator->daily()->wednesdays(); // 0 0 * * 3
// or
echo $generator->weeklyOnWednesday();

// Every thursday
echo $generator->daily()->thursdays(); // 0 0 * * 4
// or
echo $generator->weeklyOnThursday();

// Every friday
echo $generator->daily()->fridays(); // 0 0 * * 5
// or
echo $generator->weeklyOnFriday();

// Every saturday
echo $generator->daily()->saturdays(); // 0 0 * * 6
// or
echo $generator->weeklyOnSaturday();

// Every sunday
echo $generator->daily()->sundays(); // 0 0 * * 0
// or
echo $generator->weeklyOnSunday();

// Every monday
echo $generator->weeklyOn(Generator::MONDAY); // 0 0 * * 1

// Every monday at 8am 
echo $generator->weeklyOn(Generator::MONDAY, 8); // 0 8 * * 1

// Every monday at 08:06
echo $generator->weeklyOn(Generator::MONDAY, 8, 6); // 6 8 * * 1

// Every day of a week
echo $generator->set(new \Butschster\CronExpression\Parts\DaysOfWeek\EveryDayOfWeek()); // * * * * *

// Every two days of a week
echo $generator->set(new \Butschster\CronExpression\Parts\DaysOfWeek\EveryDayOfWeek(2)); // * * * * */2


// Every Monday,Wednesday, Friday
echo $generator->set(new \Butschster\CronExpression\Parts\DaysOfWeek\SpecificDaysOfWeek(Generator::MONDAY, Generator::WEDNESDAY, Generator::FRIDAY)); // * * * * 1,3,5

// Between days of a week
echo $generator->set(new \Butschster\CronExpression\Parts\DaysOfWeek\BetweenDayOfWeek(Generator::MONDAY, Generator::FRIDAY)); // * * * * 1-5

// Last monday of a week
echo $generator->set(new \Butschster\CronExpression\Parts\DaysOfWeek\LastDayOfWeek()); // * * * * 1L

// Last friday of a week
echo $generator->set(new \Butschster\CronExpression\Parts\DaysOfWeek\LastDayOfWeek(Generator::FRIDAY)); // * * * * 5L

// Every first monday of every month
echo $generator->set(new \Butschster\CronExpression\Parts\DaysOfWeek\NthDayOfWeek()); // * * * * 1#1

// Every third friday of every month
echo $generator->set(new \Butschster\CronExpression\Parts\DaysOfWeek\NthDayOfWeek(Generator::FRIDAY, 3)); // * * * * 5#3

Manipulate months

// Every month on 1-st day at 00:00
echo $generator->monthly(); // 0 0 1 * *

// Every month on 1-st day at 12:00
echo $generator->monthly(12); // 00 12 1 * *

// Every month on 1-st day at 12:30
echo $generator->monthly(12, 30); // 30 12 1 * *

// Every month on 15-st day at 12:00
echo $generator->monthlyOn(15, 12); // 0 12 15 * *

// Every month on 15-st day at 12:30
echo $generator->monthlyOn(15, 12, 30); // 30 12 15 * *

// Every month two times  on 15, 24 day at 00:00
echo $generator->twiceMonthly(15, 24); // 0 0 15,24 * *

// Every month two times  on 15, 24 day at 10:00
echo $generator->twiceMonthly(15, 24, 10); // 0 10 15,24 * *

// Every month two times  on 15, 24 day at 10:30
echo $generator->twiceMonthly(15, 24, 10, 30); // 30 10 15,24 * *

// Every month three times on 12, 24, 30 day at 10:345
echo $generator->dailyAt(10, 45)->daysOfMonth(12, 24, 30); // 45 10 12,24,30 * *

// Every quarter yyyy-01,03,06,09-01 00:00
echo $generator->quarterly(); // 0 0 1 1-12/3 *

// Every year yyyy-01-01 00:00
echo $generator->yearly(); // 0 0 1 1 *

// Every year yyyy-04-01 00:00
echo $generator->yearlyOn(Generator::APR); // 0 0 1 4 *

// Every year yyyy-04-05 00:00
echo $generator->yearlyOn(Generator::APR, 5); // 0 0 5 4 *

// Every year yyyy-04-05 08:00
echo $generator->yearlyOn(Generator::APR, 5, 8); // 0 8 5 4 *

// Every year yyyy-04-05 08:30
echo $generator->yearlyOn(Generator::APR, 5, 8, 30); // 30 8 5 4 *

// Every month
echo $generator->set(new \Butschster\CronExpression\Parts\Months\EveryMonth()); // * * * * *

// Every two months
echo $generator->set(new \Butschster\CronExpression\Parts\Months\EveryMonth(2)); // * * * */2 *

// Specific months: april and december
echo $generator->set(new \Butschster\CronExpression\Parts\Months\SpecificMonths(Generator::APR, Generator::DEC)); // * * * 4,12 *

// Between april and december
echo $generator->set(new \Butschster\CronExpression\Parts\Months\BetweenMonths(Generator::APR, Generator::DEC)); // * * * 4-12 *

// Quarterly
echo $generator->set(new \Butschster\CronExpression\Parts\Months\Quarterly()); // * * * 1-12/3 *

Specific time

$date = new DateTime('2021-02-05 12:34:26');

// Every year yyyy-02-05 12:34
echo $generator->on($date); // 34 12 5 2 *
// or
echo $generator->set(new \Butschster\CronExpression\Parts\DateTime($date)); // 34 12 5 2 *

Custom expression

use Butschster\CronExpression\Parts\Days\SpecificDays;
use Butschster\CronExpression\Parts\DaysOfWeek\SpecificDaysOfWeek;
use Butschster\CronExpression\Parts\Hours\EveryHour;
use Butschster\CronExpression\Parts\Minutes\EveryMinute;
use Butschster\CronExpression\Parts\Months\SpecificMonths;

// * */2 5,10,15,20,25,30 3,6,9,12 1,3,5,0

echo $generator
    ->yearly()
    ->months(Generator::MAR, Generator::JUN, Generator::SEP, Generator::DEC)
    ->daysOfMonth(5, 10, 15, 20, 25, 30)
    ->daysOfWeek(Generator::MONDAY, Generator::WEDNESDAY, Generator::FRIDAY, Generator::SUNDAY)
    ->everyTwoHours()
    ->everyMinute();

// or

echo $generator
    ->set(
        new SpecificMonths(Generator::MAR, Generator::JUN, Generator::SEP, Generator::DEC),
        new SpecificDays(5, 10, 15, 20, 25, 30),
        new SpecificDaysOfWeek(Generator::MONDAY, Generator::WEDNESDAY, Generator::FRIDAY, Generator::SUNDAY),
        new EveryHour(2),
        new EveryMinute()
    );

Gets next run date

See: https://github.com/dragonmantank/cron-expression#usage

echo $generator->monthlyOn(15, 12)->getExpression()->getNextRunDate(); // DateTime

Using with laravel

<?php

namespace App\Console;

use Butschster\CronExpression\Generator;
use Illuminate\Console\Scheduling\Schedule;
use Illuminate\Foundation\Console\Kernel as ConsoleKernel;
use Illuminate\Support\Facades\DB;

class Kernel extends ConsoleKernel
{
    protected function schedule(Schedule $schedule)
    {
        $schedule->command('emails:send Taylor --force')->cron(
            Generator::create()->daily()
        );
    }
}

Create custom expressions

To create a custom expression class you need implement Butschster\CronExpression\PartValueInterface

Example 1

use Butschster\CronExpression\PartValueInterface;
use Cron\CronExpression;

class Quarterly implements PartValueInterface
{
    public function updateExpression(CronExpression $expression): void
    {
        $expression->setPart(CronExpression::MONTH, '1-12/3');
    }
}

Using

echo \Butschster\CronExpression\Generator::create()->set(new Quarterly()); // * * * 1-12/3 *

Example 2

use Butschster\CronExpression\Parts\Days\SpecificDays;
use Butschster\CronExpression\Parts\Hours\SpecificHours;
use Butschster\CronExpression\Parts\Minutes\SpecificMinutes;
use Butschster\CronExpression\Parts\Months\SpecificMonths;
use Butschster\CronExpression\PartValueInterface;
use Cron\CronExpression;
use DateTimeInterface;

class DateTime implements PartValueInterface
{
    public function __construct(private DateTimeInterface $time)
    {
    }

    public function updateExpression(CronExpression $expression): void
    {
        $parts = [
            new SpecificMinutes((int)$this->time->format('i')),
            new SpecificHours((int)$this->time->format('G')),
            new SpecificDays((int)$this->time->format('j')),
            new SpecificMonths((int)$this->time->format('n'))
        ];

        foreach ($parts as $part) {
            $part->updateExpression($expression);
        }
    }
}