dragonmantank/cron-expression

PHP Cron Expression Parser

The PHP cron expression parser can parse a CRON expression, determine if it is due to run, calculate the next run date of the expression, and calculate the previous run date of the expression. You can calculate dates far into the future or past by skipping n number of matching dates.

The parser can handle increments of ranges (e.g. */12, 2-59/3), intervals (e.g. 0-9), lists (e.g. 1,2,3), W to find the nearest weekday for a given day of the month, L to find the last day of the month, L to find the last given weekday of a month, and hash (#) to find the nth weekday of a given month.

More information about this fork can be found in the blog post here. tl;dr - v2.0.0 is a major breaking change, and @dragonmantank can better take care of the project in a separate fork.

Installing

Add the dependency to your project:

composer require dragonmantank/cron-expression

Usage

<?php

require_once '/vendor/autoload.php';

// Works with predefined scheduling definitions
$cron = new Cron\CronExpression('@daily');
$cron->isDue();
echo $cron->getNextRunDate()->format('Y-m-d H:i:s');
echo $cron->getPreviousRunDate()->format('Y-m-d H:i:s');

// Works with complex expressions
$cron = new Cron\CronExpression('3-59/15 6-12 */15 1 2-5');
echo $cron->getNextRunDate()->format('Y-m-d H:i:s');

// Calculate a run date two iterations into the future
$cron = new Cron\CronExpression('@daily');
echo $cron->getNextRunDate(null, 2)->format('Y-m-d H:i:s');

// Calculate a run date relative to a specific time
$cron = new Cron\CronExpression('@monthly');
echo $cron->getNextRunDate('2010-01-12 00:00:00')->format('Y-m-d H:i:s');

CRON Expressions

A CRON expression is a string representing the schedule for a particular command to execute. The parts of a CRON schedule are as follows:

*   *   *   *   *
-   -   -   -   -
|   |   |   |   |
|   |   |   |   |
|   |   |   |   +----- day of week (0-7) (Sunday = 0 or 7) (or SUN-SAT)
|   |   |   +--------- month (1-12) (or JAN-DEC)
|   |   +------------- day of month (1-31)
|   +----------------- hour (0-23)
+--------------------- minute (0-59)

Each part of expression can also use wildcard, lists, ranges and steps:

• wildcard - match always
  • * * * * * - At every minute.
  • day of week and day of month also support ?, an alias to *
• lists - match list of values, ranges and steps
  • e.g. 15,30 * * * * - At minute 15 and 30.
• ranges - match values in range
  • e.g. 1-9 * * * * - At every minute from 1 through 9.
• steps - match every nth value in range
  • e.g. */5 * * * * - At every 5th minute.
  • e.g. 0-30/5 * * * * - At every 5th minute from 0 through 30.
• combinations
  • e.g. 0-14,30-44 * * * * - At every minute from 0 through 14 and every minute from 30 through 44.

You can also use macro instead of an expression:

• @yearly, @annually - At 00:00 on 1st of January. (same as 0 0 1 1 *)
• @monthly - At 00:00 on day-of-month 1. (same as 0 0 1 * *)
• @weekly - At 00:00 on Sunday. (same as 0 0 * * 0)
• @daily, @midnight - At 00:00. (same as 0 0 * * *)
• @hourly - At minute 0. (same as 0 * * * *)

Day of month extra features:

• nearest weekday - weekday (Monday-Friday) nearest to the given day
  • e.g. * * 15W * * - At every minute on a weekday nearest to the 15th.
  • If you were to specify 15W as the value, the meaning is: "the nearest weekday to the 15th of the month" So if the 15th is a Saturday, the trigger will fire on Friday the 14th. If the 15th is a Sunday, the trigger will fire on Monday the 16th. If the 15th is a Tuesday, then it will fire on Tuesday the 15th.
  • However, if you specify 1W as the value for day-of-month, and the 1st is a Saturday, the trigger will fire on Monday the 3rd, as it will not 'jump' over the boundary of a month's days.
• last day of the month
  • e.g. * * L * * - At every minute on a last day-of-month.
• last weekday of the month
  • e.g. * * LW * * - At every minute on a last weekday.

Day of week extra features:

• nth day
  • e.g. * * * * 7#4 - At every minute on 4th Sunday.
  • 1-5
  • Every day of week repeats 4-5 times a month. To target the last one, use "last day" feature instead.
• last day
  • e.g. * * * * 7L - At every minute on the last Sunday.

Requirements

• PHP 7.2+
• PHPUnit is required to run the unit tests
• Composer is required to run the unit tests

Projects that Use cron-expression

• Part of the Laravel Framework
• Available as a Symfony Bundle - setono/cron-expression-bundle
• Used in CakePHP QueueScheduler plugin
• Framework agnostic, PHP-based job scheduler - Crunz
• Framework agnostic job scheduler - with locks, parallelism, per-second scheduling and more - orisai/scheduler
• Explain expression in English (and other languages) with orisai/cron-expression-explainer