Debian Codegraph @

vendor/dragonmantank/cron-expression/README.md

raw
1 PHP Cron Expression Parser
2 ==========================
3
4 [![Latest Stable Version](https://poser.pugx.org/dragonmantank/cron-expression/v)](https://packagist.org/packages/dragonmantank/cron-expression) [![Total Downloads](https://poser.pugx.org/dragonmantank/cron-expression/downloads)](https://packagist.org/packages/dragonmantank/cron-expression) [![Tests](https://github.com/dragonmantank/cron-expression/actions/workflows/tests.yml/badge.svg)](https://github.com/dragonmantank/cron-expression/actions/workflows/tests.yml) [![StyleCI](https://github.styleci.io/repos/103715337/shield?branch=master)](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)