| 1 |
PHP Cron Expression Parser |
| 2 |
========================== |
| 3 |
|
| 4 |
[](https://packagist.org/packages/dragonmantank/cron-expression) [](https://packagist.org/packages/dragonmantank/cron-expression) [](https://github.com/dragonmantank/cron-expression/actions/workflows/tests.yml) [](https://github.styleci.io/repos/103715337) |
| 5 |
|
| 6 |
The PHP cron expression parser can parse a CRON expression, determine if it is |
| 7 |
due to run, calculate the next run date of the expression, and calculate the previous |
| 8 |
run date of the expression. You can calculate dates far into the future or past by |
| 9 |
skipping **n** number of matching dates. |
| 10 |
|
| 11 |
The parser can handle increments of ranges (e.g. */12, 2-59/3), intervals (e.g. 0-9), |
| 12 |
lists (e.g. 1,2,3), **W** to find the nearest weekday for a given day of the month, **L** to |
| 13 |
find the last day of the month, **L** to find the last given weekday of a month, and hash |
| 14 |
(#) to find the nth weekday of a given month. |
| 15 |
|
| 16 |
More information about this fork can be found in the blog post [here](http://ctankersley.com/2017/10/12/cron-expression-update/). tl;dr - v2.0.0 is a major breaking change, and @dragonmantank can better take care of the project in a separate fork. |
| 17 |
|
| 18 |
Installing |
| 19 |
========== |
| 20 |
|
| 21 |
Add the dependency to your project: |
| 22 |
|
| 23 |
```bash |
| 24 |
composer require dragonmantank/cron-expression |
| 25 |
``` |
| 26 |
|
| 27 |
Usage |
| 28 |
===== |
| 29 |
```php |
| 30 |
<?php |
| 31 |
|
| 32 |
require_once '/vendor/autoload.php'; |
| 33 |
|
| 34 |
// Works with predefined scheduling definitions |
| 35 |
$cron = new Cron\CronExpression('@daily'); |
| 36 |
$cron->isDue(); |
| 37 |
echo $cron->getNextRunDate()->format('Y-m-d H:i:s'); |
| 38 |
echo $cron->getPreviousRunDate()->format('Y-m-d H:i:s'); |
| 39 |
|
| 40 |
// Works with complex expressions |
| 41 |
$cron = new Cron\CronExpression('3-59/15 6-12 */15 1 2-5'); |
| 42 |
echo $cron->getNextRunDate()->format('Y-m-d H:i:s'); |
| 43 |
|
| 44 |
// Calculate a run date two iterations into the future |
| 45 |
$cron = new Cron\CronExpression('@daily'); |
| 46 |
echo $cron->getNextRunDate(null, 2)->format('Y-m-d H:i:s'); |
| 47 |
|
| 48 |
// Calculate a run date relative to a specific time |
| 49 |
$cron = new Cron\CronExpression('@monthly'); |
| 50 |
echo $cron->getNextRunDate('2010-01-12 00:00:00')->format('Y-m-d H:i:s'); |
| 51 |
``` |
| 52 |
|
| 53 |
CRON Expressions |
| 54 |
================ |
| 55 |
|
| 56 |
A CRON expression is a string representing the schedule for a particular command to execute. The parts of a CRON schedule are as follows: |
| 57 |
|
| 58 |
``` |
| 59 |
* * * * * |
| 60 |
- - - - - |
| 61 |
| | | | | |
| 62 |
| | | | | |
| 63 |
| | | | +----- day of week (0-7) (Sunday = 0 or 7) (or SUN-SAT) |
| 64 |
| | | +--------- month (1-12) (or JAN-DEC) |
| 65 |
| | +------------- day of month (1-31) |
| 66 |
| +----------------- hour (0-23) |
| 67 |
+--------------------- minute (0-59) |
| 68 |
``` |
| 69 |
|
| 70 |
Each part of expression can also use wildcard, lists, ranges and steps: |
| 71 |
|
| 72 |
- wildcard - match always |
| 73 |
- `* * * * *` - At every minute. |
| 74 |
- day of week and day of month also support `?`, an alias to `*` |
| 75 |
- lists - match list of values, ranges and steps |
| 76 |
- e.g. `15,30 * * * *` - At minute 15 and 30. |
| 77 |
- ranges - match values in range |
| 78 |
- e.g. `1-9 * * * *` - At every minute from 1 through 9. |
| 79 |
- steps - match every nth value in range |
| 80 |
- e.g. `*/5 * * * *` - At every 5th minute. |
| 81 |
- e.g. `0-30/5 * * * *` - At every 5th minute from 0 through 30. |
| 82 |
- combinations |
| 83 |
- e.g. `0-14,30-44 * * * *` - At every minute from 0 through 14 and every minute from 30 through 44. |
| 84 |
|
| 85 |
You can also use macro instead of an expression: |
| 86 |
|
| 87 |
- `@yearly`, `@annually` - At 00:00 on 1st of January. (same as `0 0 1 1 *`) |
| 88 |
- `@monthly` - At 00:00 on day-of-month 1. (same as `0 0 1 * *`) |
| 89 |
- `@weekly` - At 00:00 on Sunday. (same as `0 0 * * 0`) |
| 90 |
- `@daily`, `@midnight` - At 00:00. (same as `0 0 * * *`) |
| 91 |
- `@hourly` - At minute 0. (same as `0 * * * *`) |
| 92 |
|
| 93 |
Day of month extra features: |
| 94 |
|
| 95 |
- nearest weekday - weekday (Monday-Friday) nearest to the given day |
| 96 |
- e.g. `* * 15W * *` - At every minute on a weekday nearest to the 15th. |
| 97 |
- If you were to specify `15W` as the value, the meaning is: "the nearest weekday to the 15th of the month" |
| 98 |
So if the 15th is a Saturday, the trigger will fire on Friday the 14th. |
| 99 |
If the 15th is a Sunday, the trigger will fire on Monday the 16th. |
| 100 |
If the 15th is a Tuesday, then it will fire on Tuesday the 15th. |
| 101 |
- However, if you specify `1W` as the value for day-of-month, |
| 102 |
and the 1st is a Saturday, the trigger will fire on Monday the 3rd, |
| 103 |
as it will not 'jump' over the boundary of a month's days. |
| 104 |
- last day of the month |
| 105 |
- e.g. `* * L * *` - At every minute on a last day-of-month. |
| 106 |
- last weekday of the month |
| 107 |
- e.g. `* * LW * *` - At every minute on a last weekday. |
| 108 |
|
| 109 |
Day of week extra features: |
| 110 |
|
| 111 |
- nth day |
| 112 |
- e.g. `* * * * 7#4` - At every minute on 4th Sunday. |
| 113 |
- 1-5 |
| 114 |
- Every day of week repeats 4-5 times a month. To target the last one, use "last day" feature instead. |
| 115 |
- last day |
| 116 |
- e.g. `* * * * 7L` - At every minute on the last Sunday. |
| 117 |
|
| 118 |
Requirements |
| 119 |
============ |
| 120 |
|
| 121 |
- PHP 7.2+ |
| 122 |
- PHPUnit is required to run the unit tests |
| 123 |
- Composer is required to run the unit tests |
| 124 |
|
| 125 |
Projects that Use cron-expression |
| 126 |
================================= |
| 127 |
* Part of the [Laravel Framework](https://github.com/laravel/framework/) |
| 128 |
* Available as a [Symfony Bundle - setono/cron-expression-bundle](https://github.com/Setono/CronExpressionBundle) |
| 129 |
* Framework agnostic, PHP-based job scheduler - [Crunz](https://github.com/crunzphp/crunz) |
| 130 |
* Framework agnostic job scheduler - with locks, parallelism, per-second scheduling and more - [orisai/scheduler](https://github.com/orisai/scheduler) |
| 131 |
* Explain expression in English (and other languages) with [orisai/cron-expression-explainer](https://github.com/orisai/cron-expression-explainer) |