Cron Expression

https://github.com/dragonmantank/cron-expression
Admin
A PHP library that parses CRON expressions to determine if they are due to run and calculate their...
Tokens:50,840
Snippets:350
Trust Score:9.8
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### getMultipleRunDates usage example

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Example of getting the next 5 run dates for a workday schedule, including the current date if it matches.

```php
$cron = new CronExpression('*/15 9-17 * * 1-5');
$runs = $cron->getMultipleRunDates(5, '2024-01-01 00:00:00', false, true);
foreach ($runs as $run) {
    echo $run->format('Y-m-d H:i:s') . "\n";
}
```

--------------------------------

### getExpression usage examples

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Examples of retrieving the minute part, an invalid key, and the full expression.

```php
$cron = new CronExpression('1 2-4 * 4,5,6 */3');
$cron->getExpression(CronExpression::MINUTE); // '1'
$cron->getExpression('foo');                  // null
$cron->getExpression();                       // '1 2-4 * 4,5,6 */3'
```

--------------------------------

### Install cron-expression with Composer

Source: https://github.com/dragonmantank/cron-expression/blob/master/README.md

Install the cron-expression package via Composer. Run this in your project root to add the dependency.

```bash
composer require dragonmantank/cron-expression
```

--------------------------------

### __toString() usage example

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Example of casting a CronExpression to string, which returns the expanded expression.

```php
$cron = new CronExpression('@weekly');
echo (string) $cron; // '0 0 * * 0'
```

--------------------------------

### getNextRunDate usage examples

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Examples of calling getNextRunDate with different parameters: default, skipping matches, and specifying a timezone.

```php
$cron = new CronExpression('@daily');
echo $cron->getNextRunDate()->format('Y-m-d H:i:s');
echo $cron->getNextRunDate(null, 2)->format('Y-m-d H:i:s');      // 2 matches ahead
echo $cron->getNextRunDate('2010-01-12 00:00:00', 0, false, 'America/New_York')->format('Y-m-d H:i:s');
```

--------------------------------

### getPreviousRunDate usage example

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Example of getting the previous run date for a monthly cron expression.

```php
$cron = new CronExpression('@monthly');
echo $cron->getPreviousRunDate()->format('Y-m-d H:i:s');
```

--------------------------------

### increment usage example

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/MinutesField.md

Example of using increment to advance to the next minute matching '15,30,45' and then to the next minute without parts. Outputs 14:15 and then 14:16.

```php
$d = new DateTime('2024-01-15 14:10:00');
$f = new MinutesField();
$f->increment($d, false, '15,30,45');
echo $d->format('Y-m-d H:i:s'); // 2024-01-15 14:15:00

$f->increment($d);
echo $d->format('Y-m-d H:i:s'); // 2024-01-15 14:16:00
```

--------------------------------

### getMultipleRunDates previous dates example

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Example of getting the previous 3 run dates using the invert parameter.

```php
// Previous 3 run dates
$prevRuns = $cron->getMultipleRunDates(3, '2024-01-15 12:00:00', true);
```

--------------------------------

### MinutesField usage example

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/AbstractField.md

Example usage of a concrete field. Creates a MinutesField and checks if the value 15 satisfies the expression '15'.

```php
$f = new MinutesField();     // rangeStart 0, rangeEnd 59
$f->isSatisfied(15, '15');   // true
```

--------------------------------

### increment usage example

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/MonthField.md

Example usage of increment. It shows forward increment to the first day of the next month at 00:00:00, and backward increment to the last day of the previous month at 23:59:00.

```php
$d = new DateTime('2024-01-15 11:15:00');
$f = new MonthField();
$f->increment($d);
echo $d->format('Y-m-d H:i:s'); // 2024-02-01 00:00:00
$f->increment($d, true);
echo $d->format('Y-m-d H:i:s'); // 2024-01-31 23:59:00

```

--------------------------------

### getParts() usage example

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Example usage of getParts() to retrieve the month part of a cron expression.

```php
$cron = new CronExpression('0 0 1 1 *');
$parts = $cron->getParts();
echo $parts[CronExpression::MONTH]; // '1'
```

--------------------------------

### Step CRON expression (wildcard step)

Source: https://github.com/dragonmantank/cron-expression/blob/master/README.md

Step example: matches every 5th minute.

```text
*/5 * * * *
```

--------------------------------

### List CRON expression

Source: https://github.com/dragonmantank/cron-expression/blob/master/README.md

List example: matches at minute 15 and 30.

```text
15,30 * * * *
```

--------------------------------

### isSatisfiedBy usage examples

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/DayOfWeekField.md

Usage examples for isSatisfiedBy with literal, list, L, and # values. Comments show expected results.

```php
use Cron\DayOfWeekField;
use DateTime;

$f = new DayOfWeekField();
$f->isSatisfiedBy(new DateTime('2024-01-15 00:00:00'), 'MON', false); // true (Monday)
$f->isSatisfiedBy(new DateTime('2024-01-15 00:00:00'), '1,3,5', false); // true
$f->isSatisfiedBy(new DateTime('2024-01-28 00:00:00'), '7L', false);  // last Sunday of January 2024
$f->isSatisfiedBy(new DateTime('2024-01-08 00:00:00'), '1#2', false); // 2nd Monday of the month
```

--------------------------------

### isInIncrementsOfRanges method signature, usage, and exception handling

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/AbstractField.md

Method signature, usage example, and exception handling example for isInIncrementsOfRanges. Returns true if the date value matches the step expression. Step 0 returns false, and out-of-range values throw OutOfRangeException.

```php
public function isInIncrementsOfRanges(int $dateValue, string $value): bool
```

```php
$f = new MinutesField();
$f->isInIncrementsOfRanges(3, '3-59/2');  // true
$f->isInIncrementsOfRanges(0, '*/0');     // false (step 0)
```

```php
try {
    $f->isInIncrementsOfRanges(1, '60-61/2');
} catch (OutOfRangeException $e) {
    // 'Invalid range start requested'
}
```

--------------------------------

### getPreviousRunDate with specific time

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Example of getting the previous run date relative to a specific DateTime, showing the result in the input's timezone.

```php
$cron = new CronExpression('0 7 * * *');
$prev = $cron->getPreviousRunDate(new DateTime('2017-10-17 10:00:00'));
echo $prev->format('Y-m-d H:i:s'); // 2017-10-17 07:00:00 in the input's timezone
```

--------------------------------

### isDue() with timezone example

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Example of isDue() with a timezone override.

```php
$cron = new CronExpression('0 7 * * *');
$cron->isDue('2024-01-15 07:30:00', 'Asia/Tokyo');
```

--------------------------------

### isDue() usage example

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Example of isDue() with default timezone and a specific datetime.

```php
$cron = new CronExpression('@daily');
$cron->isDue();                      // true during the 00:00 minute (system tz)
$cron->isDue('2024-01-15 10:00:00'); // false
```

--------------------------------

### Step CRON expression (range step)

Source: https://github.com/dragonmantank/cron-expression/blob/master/README.md

Step example: matches every 5th minute from 0 through 30.

```text
0-30/5 * * * *
```

--------------------------------

### increment usage example

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/HoursField.md

Example usage of increment with a part constraint '9-17'. The output shows the date advanced to the next hour within the allowed range.

```php
$d = new DateTime('2024-01-15 14:30:00');
$f = new HoursField();
$f->increment($d, false, '9-17');
echo $d->format('Y-m-d H:i:s'); // 2024-01-15 15:00:00
```

--------------------------------

### Injecting SpyFactory into CronExpression

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/FieldFactoryInterface.md

Usage example showing how to inject a custom factory into CronExpression and trigger a call that routes through the spy factory.

```php
use Cron\CronExpression;

$cron = new CronExpression('@daily', new SpyFactory());
$cron->isDue('2024-01-15 00:00:00'); // routed through the spy factory

```

--------------------------------

### Wildcard CRON expression

Source: https://github.com/dragonmantank/cron-expression/blob/master/README.md

Wildcard example: matches every minute.

```text
* * * * *
```

--------------------------------

### DayOfWeekField::validate() usage examples

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/DayOfWeekField.md

Examples of valid and invalid values for the validate() method, including ranges, nth occurrences, '?', and invalid patterns.

```php
$f = new DayOfWeekField();
$f->validate('MON-FRI'); // true
$f->validate('SUN-2');   // true
$f->validate('7#4');     // true
$f->validate('?');       // true
$f->validate('*/3,1,1-12'); // false
$f->validate('1.');      // false
```

--------------------------------

### Custom SpyFactory implementing FieldFactoryInterface

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/FieldFactoryInterface.md

Example of a custom factory implementation that wraps the default FieldFactory to intercept or observe field accesses. Useful for testing or logging purposes.

```php
use Cron\FieldFactoryInterface;
use Cron\FieldInterface;

class SpyFactory implements FieldFactoryInterface
{
    private $inner;

    public function __construct()
    {
        $this->inner = new FieldFactory();
    }

    public function getField(int $position): FieldInterface
    {
        $field = $this->inner->getField($position);
        // observe $field here, then return it
        return $field;
    }
}

```

--------------------------------

### Basic usage of Cron\CronExpression

Source: https://github.com/dragonmantank/cron-expression/blob/master/README.md

Basic usage of the Cron\CronExpression class. It demonstrates checking if due, getting next/previous run dates, calculating future runs with a skip count, and using a specific time. Requires the Composer autoloader.

```php
<?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');
```

--------------------------------

### Combination CRON expression

Source: https://github.com/dragonmantank/cron-expression/blob/master/README.md

Combination example: matches every minute from 0 through 14 and every minute from 30 through 44.

```text
0-14,30-44 * * * *
```

--------------------------------

### Range CRON expression

Source: https://github.com/dragonmantank/cron-expression/blob/master/README.md

Range example: matches every minute from 1 through 9.

```text
1-9 * * * *
```

--------------------------------

### getPastTransition usage example

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/HoursField.md

Example usage of getPastTransition with a DST-sensitive date. The comment notes that the result is non-null around DST switch dates.

```php
$f = new HoursField();
$zone = new DateTimeZone('America/New_York');
$d = DateTime::createFromFormat('!Y-m-d H:i:s', '2024-03-15 12:00:00', $zone);
$t = $f->getPastTransition($d); // non-null around DST switch dates
```

--------------------------------

### isRange method implementation and usage

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/AbstractField.md

Method implementation and usage example for isRange. Returns true if the value contains a hyphen. The example uses DayOfWeekField to test range detection.

```php
public function isRange(string $value): bool
{
    return false !== strpos($value, '-');
}
```

```php
$f = new DayOfWeekField();
$f->isRange('1-2'); // true
$f->isRange('2');   // false
```

--------------------------------

### getNextRunDate exception handling

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Example of catching a RuntimeException when the cron expression has no valid run date (e.g., February 30).

```php
try {
    $cron = new CronExpression('0 0 30 2 *');
    $cron->getNextRunDate(); // no such date exists
} catch (RuntimeException $e) {
    // 'Impossible CRON expression'
}
```

--------------------------------

### Create CronExpression and get next run date

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Creates a CronExpression instance with a complex expression and prints the next run date formatted as 'Y-m-d H:i:s'.

```php
use Cron\CronExpression;

$cron = new CronExpression('3-59/15 6-12 */15 1 2-5');
echo $cron->getNextRunDate()->format('Y-m-d H:i:s'); // next match
```

--------------------------------

### DayOfWeekField::increment() usage example

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/DayOfWeekField.md

Example of using increment() with $invert set to true to rewind the date to the previous day, resulting in 2011-03-14 23:59:00.

```php
$d = new DateTime('2011-03-15 11:15:00');
$f = new DayOfWeekField();
$f->increment($d, true);
echo $d->format('Y-m-d H:i:s'); // 2011-03-14 23:59:00
```

--------------------------------

### Validate day-of-month expressions with DayOfMonthField

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/DayOfMonthField.md

Example validation results for various day-of-month values. Lists containing W or L are rejected; '?' and 'L' are accepted, and W-day patterns with a valid prefix pass.

```php
$f = new DayOfMonthField();
$f->validate('1');    // true
$f->validate('L');    // true
$f->validate('5W');   // true
$f->validate('LW');   // true (via the W regex, prefix 'L' validates)
$f->validate('5W,L'); // false
$f->validate('1.');   // false
```

--------------------------------

### isSatisfiedBy usage example

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/MinutesField.md

Example of using isSatisfiedBy to test if a date matches a '*/15' minute expression. Returns true for 14:15 and false for 14:16.

```php
use Cron\MinutesField;
use DateTime;

$f = new MinutesField();
$f->isSatisfiedBy(new DateTime('2024-01-15 14:15:00'), '*/15', false); // true
$f->isSatisfiedBy(new DateTime('2024-01-15 14:16:00'), '*/15', false); // false
```

--------------------------------

### isInRange method signature and usage

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/AbstractField.md

Method signature and usage example for isInRange. Returns true if the date value is within the given range. The example uses DayOfWeekField to test a range.

```php
public function isInRange(int $dateValue, $value): bool
```

```php
$f = new DayOfWeekField();
$f->isInRange(2, '1-5'); // true
```

--------------------------------

### Last weekday CRON expression

Source: https://github.com/dragonmantank/cron-expression/blob/master/README.md

Last weekday of month example: matches every minute on the last weekday of the month.

```text
* * LW * *
```

--------------------------------

### isIncrementsOfRanges method implementation and usage

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/AbstractField.md

Method implementation and usage example for isIncrementsOfRanges. Returns true if the value contains a slash. The example uses HoursField to test step expression detection.

```php
public function isIncrementsOfRanges(string $value): bool
{
    return false !== strpos($value, '/');
}
```

```php
$f = new HoursField();
$f->isIncrementsOfRanges('*/2');   // true
$f->isIncrementsOfRanges('3-12/2'); // true
```

--------------------------------

### isSatisfiedBy usage example

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/MonthField.md

Example usage of isSatisfiedBy with a MonthField instance. It demonstrates matching a month literal ('APR'), a range ('1-6'), and a non-matching literal ('JAN'), returning true, true, and false respectively.

```php
use Cron\MonthField;
use DateTime;

$f = new MonthField();
$f->isSatisfiedBy(new DateTime('2024-04-15 00:00:00'), 'APR', false); // true
$f->isSatisfiedBy(new DateTime('2024-04-15 00:00:00'), '1-6', false); // true
$f->isSatisfiedBy(new DateTime('2024-07-15 00:00:00'), 'JAN', false); // false

```

--------------------------------

### isSatisfied method signature and usage

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/AbstractField.md

Method signature and usage example for isSatisfied. Returns true when the value is '*', equals the date value, is within a step expression, or is within a range. The example uses HoursField to test various CRON expressions.

```php
public function isSatisfied(int $dateValue, string $value): bool
```

```php
$f = new HoursField();
$f->isSatisfied(12, '*');        // true
$f->isSatisfied(12, '9-17');     // true
$f->isSatisfied(12, '*/3');      // true
$f->isSatisfied(12, '11');       // false
```

--------------------------------

### Cron\FieldFactoryInterface

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/types.md

Contract for resolving field objects by expression position, with a single method to get a field by position.

```APIDOC
## Cron\FieldFactoryInterface

### Description
Contract for resolving field objects by expression position.

### Methods

#### getField
- **Signature**: `public function getField(int $position): FieldInterface;`
- **Description**: Returns the field object for the given position in the cron expression.

### Usage
Accepted by: `CronExpression::__construct(string $expression, ?FieldFactoryInterface $fieldFactory = null)` and the deprecated `CronExpression::factory(...)`. Implemented by `Cron\FieldFactory`.
```

--------------------------------

### Last day of month CRON expression

Source: https://github.com/dragonmantank/cron-expression/blob/master/README.md

Last day of month example: matches every minute on the last day of the month.

```text
* * L * *
```

--------------------------------

### Increment and rewind a date with DayOfMonthField

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/DayOfMonthField.md

Example usage of increment() with and without the $invert flag. Forward increments to the next day at 00:00:00; rewind (true) goes back to the previous day at 23:59:00.

```php
$d = new DateTime('2011-03-15 11:15:00');
$f = new DayOfMonthField();
$f->increment($d);
echo $d->format('Y-m-d H:i:s'); // 2011-03-16 00:00:00
$f->increment($d, true);
echo $d->format('Y-m-d H:i:s'); // 2011-03-15 23:59:00
```

--------------------------------

### isSatisfiedBy usage with L, W, and ?

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/DayOfMonthField.md

Example usage of isSatisfiedBy with the special values 'L', '15W', and '?'. The comments show the expected boolean results for each call.

```php
use Cron\DayOfMonthField;
use DateTime;

$f = new DayOfMonthField();
$f->isSatisfiedBy(new DateTime('2024-01-31 00:00:00'), 'L', false);  // true
$f->isSatisfiedBy(new DateTime('2024-01-15 00:00:00'), '15W', false); // true
$f->isSatisfiedBy(new DateTime('2024-01-15 00:00:00'), '?', false);  // true

```

--------------------------------

### Nearest weekday CRON expression

Source: https://github.com/dragonmantank/cron-expression/blob/master/README.md

Nearest weekday example: matches every minute on a weekday nearest to the 15th. If the 15th is a Saturday, it fires on Friday the 14th; if Sunday, on Monday the 16th; if Tuesday, on Tuesday the 15th. For 1W, it will not jump over the month boundary.

```text
* * 15W * *
```

--------------------------------

### Catch RuntimeException for impossible CRON expression

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/errors.md

Shows how to trigger and catch the 'Impossible CRON expression' RuntimeException. The example sets a custom max iteration count (50) and calls getNextRunDate() on an invalid expression (Feb 30). The catch block comments the expected exception message.

```php
$cron = new CronExpression('0 0 30 2 *');
$cron->setMaxIterationCount(50);
try {
    $cron->getNextRunDate();
} catch (RuntimeException $e) {
    // 'Impossible CRON expression'
}
```

--------------------------------

### Custom factory implementing FieldFactoryInterface

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/FieldFactory.md

Shows how to implement a custom factory for testing or dependency injection, wrapping the default factory to return field instances.

```php
use Cron\FieldFactoryInterface;
use Cron\FieldInterface;

class RecordingFactory implements FieldFactoryInterface
{
    public function getField(int $position): FieldInterface
    {
        // e.g. wrap the default factory or return doubles
        return (new FieldFactory())->getField($position);
    }
}
```

--------------------------------

### setTimeHour: Set hour boundary with DST correction

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/AbstractField.md

Sets the time to the start (H:00) or end (H:59) of the hour based on the invert flag, then corrects by ±1 hour if the setTime call moved the instant across a DST offset boundary in the wrong direction. The original timestamp is used to detect offset shifts.

```php
protected function setTimeHour(DateTimeInterface $date, bool $invert, int $originalTimestamp): DateTimeInterface
```

--------------------------------

### List all registered aliases

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Iterates over all registered aliases and prints each alias and its corresponding CRON expression.

```php
foreach (CronExpression::getAliases() as $alias => $expression) {
    echo $alias . ' => ' . $expression . "\n";
}
```

--------------------------------

### __toString(): string

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Returns the full cron expression as a string. Invoked by string casts and interpolation.

```APIDOC
## __toString(): string

### Description
Returns the full cron expression as a string. Invoked when the object is cast to string or interpolated.

### Method
`__toString(): string`

### Signature
```php
public function __toString(): string
```

### Parameters
None.

### Return Value
- **Type**: `string`
- **Description**: The full cron expression string.

### Example
```php
$cron = new CronExpression('@weekly');
echo (string) $cron; // '0 0 * * 0'
```
```

--------------------------------

### Using custom factory with CronExpression

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/FieldFactory.md

Instantiates a CronExpression with a custom RecordingFactory to replace the default field factory.

```php
use Cron\CronExpression;

$cron = new CronExpression('0 0 * * *', new RecordingFactory());
```

--------------------------------

### Using FieldFactory with CronExpression constants

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/FieldFactory.md

Creates a FieldFactory instance and retrieves a field for the MONTH position, demonstrating that the same instance is cached and returned on subsequent calls.

```php
use Cron\CronExpression;
use Cron\FieldFactory;

$factory = new FieldFactory();
$f = $factory->getField(CronExpression::MONTH);  // MonthField
$factory->getField(CronExpression::MONTH) === $f; // true (cached instance)
```

--------------------------------

### Usage example for HoursField::isSatisfiedBy

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/HoursField.md

Example of using HoursField to check if a date satisfies a range. The first call returns true for 14:30 within 9-17, the second returns false for 20:00.

```php
use Cron\HoursField;
use DateTime;

$f = new HoursField();
$f->isSatisfiedBy(new DateTime('2024-01-15 14:30:00'), '9-17', false); // true
$f->isSatisfiedBy(new DateTime('2024-01-15 20:00:00'), '9-17', false); // false

```

--------------------------------

### __toString() method signature

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Returns the full cron expression as a string. Invoked by string casts and interpolation.

```php
public function __toString(): string
```

--------------------------------

### CronExpression::__construct

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Constructor for creating a CronExpression instance.

```APIDOC
## Constructor

### Description
Creates a new CronExpression instance from a CRON expression string or a registered alias.

### Signature
```php
public function __construct(string $expression, ?FieldFactoryInterface $fieldFactory = null)
```

### Parameters
- **$expression** (string) - Required - CRON expression (e.g. `'8 * * * *'`) or registered alias (e.g. `'@daily'`, resolved case-insensitively)
- **$fieldFactory** (?FieldFactoryInterface) - Optional - Inject a custom field factory; `null` uses a new `FieldFactory`

### Throws
- `\InvalidArgumentException` on validation failure

### Example
```php
use Cron\CronExpression;

$cron = new CronExpression('3-59/15 6-12 */15 1 2-5');
echo $cron->getNextRunDate()->format('Y-m-d H:i:s'); // next match
```

```php
try {
    $cron = new CronExpression('61 * * * *'); // minute 61 is out of range
} catch (InvalidArgumentException $e) {
    // 'Invalid CRON field value 61 at position 0'
}
```
```

--------------------------------

### Check alias support

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Checks if aliases are supported. '@daily' is built-in and returns true; '@every' returns false unless it has been registered.

```php
CronExpression::supportsAlias('@daily'); // true
CronExpression::supportsAlias('@every');  // false unless registered
```

--------------------------------

### CRON expression field layout

Source: https://github.com/dragonmantank/cron-expression/blob/master/README.md

Shows the five fields of a CRON expression and their allowed values. The order is minute, hour, day of month, month, and day of week.

```text
*   *   *   *   *
-   -   -   -   -
|   |   |   |   |
|   |   |   |   |
|   |   |   |   +----- 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)
```

--------------------------------

### Construct CronExpression with custom FieldFactory

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/configuration.md

Shows the primary constructor usage with a custom FieldFactory instance. The expression is checked case-insensitively against registered aliases, otherwise parsed as 5 whitespace-separated parts. The fieldFactory parameter is optional and defaults to a new FieldFactory() when null.

```php
use Cron\CronExpression;
use Cron\FieldFactory;

$cron = new CronExpression('0 */15 * * 1-5', new FieldFactory());
```

--------------------------------

### Attempt to register a built-in alias

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Attempts to register a built-in alias, which throws a LogicException with the message 'The alias `@daily` is already registered.'

```php
try {
    CronExpression::registerAlias('@daily', '0 0 * * *'); // already a built-in
} catch (LogicException $e) {
    // "The alias `@daily` is already registered."
}
```

--------------------------------

### Cron\CronExpression::getMultipleRunDates

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Returns an array of multiple future run dates that match the CRON expression, starting from a given date.

```APIDOC
## Cron\CronExpression::getMultipleRunDates

### Description
Returns an array of multiple future run dates that match the CRON expression, starting from a given date.

### Method
getMultipleRunDates

### Signature
```php
public function getMultipleRunDates(int $total, \DateTimeInterface $currentTime, bool $invert = false, bool $allowCurrentDate = false, ?string $timezone = null): array
```

### Parameters
- **total** (int) - Required - The number of run dates to return.
- **currentTime** (DateTimeInterface) - Required - The starting date/time.
- **invert** (bool) - Optional - If true, returns previous run dates instead of future ones. Defaults to false.
- **allowCurrentDate** (bool) - Optional - If true, the current date is allowed as a match. Defaults to false.
- **timezone** (string|null) - Optional - The timezone to use. Defaults to the current time's timezone.

### Return Value
- **array** - An array of DateTimeInterface objects representing the run dates.

### Example
```php
$cron = new Cron\CronExpression('0 0 * * *');
$dates = $cron->getMultipleRunDates(5, new DateTime('2023-01-01 00:00:00'));
```
```

--------------------------------

### AbstractField constructor

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/AbstractField.md

Constructor that builds the full allowed value set from the subclass-defined rangeStart and rangeEnd. Called automatically when a concrete field is instantiated.

```php
public function __construct()
{
    $this->fullRange = range($this->rangeStart, $this->rangeEnd);
}
```

--------------------------------

### Set expression and chain methods

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Demonstrates chaining setExpression and setMaxIterationCount. Casting to string returns the new expression '0 0 * * 1-5'.

```php
$cron = new CronExpression('* * * * *');
$cron->setExpression('0 0 * * 1-5')->setMaxIterationCount(500);
echo (string) $cron; // '0 0 * * 1-5'
```

--------------------------------

### Catching invalid nth weekday error

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/DayOfWeekField.md

Example of catching an InvalidArgumentException when the nth weekday is out of range (6). The error message is shown in the comment.

```php
try {
    $f->isSatisfiedBy(new DateTime('2024-01-08 00:00:00'), '1#6', false);
} catch (InvalidArgumentException $e) {
    // 'There are never more than 5 or less than 1 of a given weekday in a month, 6 given'
}
```

--------------------------------

### Catch LogicException from CronExpression alias methods

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/errors.md

Shows the three LogicException cases thrown by the alias registry: registering an invalid expression, registering an alias without the required '@' prefix, and unregistering a built-in alias. Each catch block documents the exact exception message.

```php
try {
    CronExpression::registerAlias('@every', 'foobar'); // not a cron expression
} catch (LogicException $e) {
    // 'The expression `foobar` is invalid' (previous: InvalidArgumentException)
}
try {
    CronExpression::registerAlias('every', '* * * * *'); // missing '@'
} catch (LogicException $e) {
    // "The alias `every` is invalid. It must start with an `@` character ..."
}
try {
    CronExpression::unregisterAlias('@daily'); // built-in
} catch (LogicException $e) {
    // 'The alias `@daily` is a built-in alias; it can not be unregistered.'
}
```

--------------------------------

### Handling invalid position with try-catch

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/FieldFactory.md

Attempts to get a field for position 5 (year), which throws an InvalidArgumentException with message '6 is not a valid position'.

```php
try {
    $factory->getField(5); // year position
} catch (InvalidArgumentException $e) {
    // '6 is not a valid position'
}
```

--------------------------------

### Cron\CronExpression::getNextRunDate

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Computes the next run date that matches the CRON expression, starting from a given date. Optionally returns multiple future run dates.

```APIDOC
## Cron\CronExpression::getNextRunDate

### Description
Computes the next run date that matches the CRON expression, starting from a given date. Optionally returns multiple future run dates.

### Method
getNextRunDate

### Signature
```php
public function getNextRunDate(\DateTimeInterface $currentTime, int $nth = 0, bool $allowCurrentDate = false, ?string $timezone = null): DateTimeInterface
```

### Parameters
- **currentTime** (DateTimeInterface) - Required - The starting date/time.
- **nth** (int) - Optional - The number of future run dates to skip (0 for the next). Defaults to 0.
- **allowCurrentDate** (bool) - Optional - If true, the current date is allowed as a match. Defaults to false.
- **timezone** (string|null) - Optional - The timezone to use. Defaults to the current time's timezone.

### Return Value
- **DateTimeInterface** - The next run date (or the nth next run date).

### Example
```php
$cron = new Cron\CronExpression('0 0 * * *');
$next = $cron->getNextRunDate(new DateTime('2023-01-01 00:00:00'));
```
```

--------------------------------

### Use factory method (deprecated)

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Creates a CronExpression using the deprecated factory method. The comment recommends using the constructor instead.

```php
$cron = CronExpression::factory('0 0 * * *'); // prefer: new CronExpression('0 0 * * *')
```

--------------------------------

### getExpression($part = null): ?string

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Returns the full cron expression or a specific part of it. If the part key does not exist, returns null.

```APIDOC
## getExpression($part = null): ?string

### Description
Returns the full cron expression or a specific part of it. If the part key does not exist, returns null.

### Method
PHP method

### Signature
```php
public function getExpression($part = null): ?string
```

### Parameters
- **$part** (int | string | null) - Optional - Position constant (MINUTE…WEEKDAY), an integer index, or any other key; null returns the whole expression

### Returns
- **?string** - Full expression (parts joined with single spaces) when $part is null; the part when the key exists in $cronParts; else null

### Example
```php
$cron = new CronExpression('1 2-4 * 4,5,6 */3');
$cron->getExpression(CronExpression::MINUTE); // '1'
$cron->getExpression('foo');                  // null
$cron->getExpression();                       // '1 2-4 * 4,5,6 */3'
```
```

--------------------------------

### getParts() method signature

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Returns the internal cron parts array. Added in v3.1.0.

```php
public function getParts()
```

--------------------------------

### Cron\CronExpression::__construct

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Creates a new CronExpression instance from a CRON expression string. The expression must be a valid 5-field CRON expression (minute, hour, day of month, month, day of week).

```APIDOC
## Cron\CronExpression::__construct

### Description
Creates a new CronExpression instance from a CRON expression string. The expression must be a valid 5-field CRON expression (minute, hour, day of month, month, day of week).

### Method
__construct

### Signature
```php
public function __construct(string $expression, ?FieldFactoryInterface $fieldFactory = null)
```

### Parameters
- **expression** (string) - Required - The CRON expression to parse.
- **fieldFactory** (FieldFactoryInterface|null) - Optional - A custom field factory to use for parsing. Defaults to null.

### Throws
- **InvalidArgumentException** - If the expression is invalid or contains an unsupported field count.

### Example
```php
$cron = new Cron\CronExpression('0 0 * * *');
```
```

--------------------------------

### isSatisfiedBy throwing RuntimeException for invalid W

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/DayOfMonthField.md

Example showing that a W value with an invalid day (32W) throws a RuntimeException with the message 'Unable to return nearest weekday' because getNearestWeekday returns null.

```php
try {
    $f->isSatisfiedBy(new DateTime('2024-01-15 00:00:00'), '32W', false);
} catch (RuntimeException $e) {
    // 'Unable to return nearest weekday' (getNearestWeekday returned null)
}

```

--------------------------------

### Declare Cron\CronExpression class

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Class declaration for Cron\CronExpression, the primary public entry point of the library. It parses a 5-field CRON expression, tests whether a date/time satisfies it (isDue), and computes next, previous, or batch run dates. Comparisons drop seconds, so determinations are accurate only if checked once per minute. When both day-of-month and day-of-week are specified they combine as an OR (v3.0.0 change). Year fields are unsupported: YEAR is deprecated and a 6th field position throws.

```php
declare(strict_types=1);

namespace Cron;

class CronExpression
```

--------------------------------

### DayOfWeekField constructor

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/DayOfWeekField.md

Constructor initializes the allowed nth weekday range (1-5) before calling the parent constructor.

```php
public function __construct()
{
    $this->nthRange = range(1, 5);
    parent::__construct();
}
```

--------------------------------

### Set hour and minute parts with chaining

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Chains setPart calls to set the hour field to '9-17' and the minute field to '*/15' on an existing CronExpression instance.

```php
$cron = new CronExpression('* * * * *');
$cron->setPart(CronExpression::HOUR, '9-17')->setPart(CronExpression::MINUTE, '*/15');
```

--------------------------------

### getRangeForExpression: Expand CRON expression to array of values

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/AbstractField.md

Expands a CRON part expression (list, range, step, or single value) into an array of matching values. Lists are expanded recursively and merged; ranges expand by step 1; steps use the range start when the offset is '*'; a step >= range end yields a single value based on modulo. Note that non-range single values are returned as strings despite the int docblock.

```php
public function getRangeForExpression(string $expression, int $max): array
```

```php
$f = new HoursField();
$f->getRangeForExpression('5-7,11-13', 23); // [5, 6, 7, 11, 12, 13]
$f->getRangeForExpression('*/6', 23);       // [0, 6, 12, 18]
```

--------------------------------

### Cron\CronExpression::getExpression

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Returns the original CRON expression string that was used to create this instance.

```APIDOC
## Cron\CronExpression::getExpression

### Description
Returns the original CRON expression string that was used to create this instance.

### Method
getExpression

### Signature
```php
public function getExpression(): string
```

### Return Value
- **string** - The CRON expression string.

### Example
```php
$cron = new Cron\CronExpression('0 0 * * *');
echo $cron->getExpression(); // '0 0 * * *'
```
```

--------------------------------

### Register a custom alias with CronExpression::registerAlias

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/configuration.md

Registers a custom alias '@workday' that expands to '0 9-17 * * 1-5' and then creates a CronExpression instance using that alias. The alias is process-wide and case-insensitive; the expansion must be a valid cron expression or a LogicException is thrown.

```php
use Cron\CronExpression;

CronExpression::registerAlias('@workday', '0 9-17 * * 1-5');
$cron = new CronExpression('@workday');
```

--------------------------------

### Register and use a custom alias

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Registers a custom alias '@every' and uses it to create a CronExpression instance. The alias must match /^@\w+$/ and the expression must be valid.

```php
use Cron\CronExpression;

CronExpression::registerAlias('@every', '* * * * *');
$cron = new CronExpression('@every');
echo $cron->getExpression(); // '* * * * *'
```

--------------------------------

### getParts()

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Returns the internal cron expression parts as an array of strings, indexed by position. Added in v3.1.0.

```APIDOC
## getParts()

### Description
Returns the internal cron expression parts as an array of strings, indexed by position (e.g., minute, hour, day, month, weekday).

### Method
`getParts()`

### Signature
```php
public function getParts()
```

### Parameters
None.

### Return Value
- **Type**: `string[]` (array of strings)
- **Description**: The cron expression parts, indexed by position. The array keys correspond to the cron part positions (e.g., `CronExpression::MONTH`).

### Example
```php
$cron = new CronExpression('0 0 1 1 *');
$parts = $cron->getParts();
echo $parts[CronExpression::MONTH]; // '1'
```
```

--------------------------------

### getPreviousRunDate method signature

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Signature of the getPreviousRunDate method. It returns the previous matching DateTime.

```php
public function getPreviousRunDate($currentTime = 'now', int $nth = 0, bool $allowCurrentDate = false, $timeZone = null): DateTime
```

--------------------------------

### getField method implementation

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/FieldFactory.md

Returns a cached field instance for the given position, creating it on first access via instantiateField. Throws InvalidArgumentException for invalid positions.

```php
public function getField(int $position): FieldInterface
{
    return $this->fields[$position] ?? $this->fields[$position] = $this->instantiateField($position);
}
```

--------------------------------

### getPastTransition method signature

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/HoursField.md

Method signature for retrieving the most recent timezone transition at or before the given date. Returns null if no transition exists within the queried window.

```php
public function getPastTransition(DateTimeInterface $date): ?array
```

--------------------------------

### Attempt to unregister a built-in alias

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Attempts to unregister a built-in alias, which throws a LogicException because built-in aliases cannot be removed.

```php
try {
    CronExpression::unregisterAlias('@daily');
} catch (LogicException $e) {
    // built-in aliases cannot be removed
}
```

--------------------------------

### getNextRunDate($currentTime = 'now', int $nth = 0, bool $allowCurrentDate = false, $timeZone = null): DateTime

Source: https://github.com/dragonmantank/cron-expression/blob/master/_autodocs/api-reference/CronExpression.md

Calculates the next run date after the given current time, with options to skip matches, allow the current date, and override the timezone. Throws RuntimeException if no valid date exists.

```APIDOC
## getNextRunDate($currentTime = 'now', int $nth = 0, bool $allowCurrentDate = false, $timeZone = null): DateTime

### Description
Calculates the next run date after the given current time, with options to skip matches, allow the current date, and override the timezone. Throws RuntimeException if no valid date exists.

### Method
PHP method

### Signature
```php
public function getNextRunDate($currentTime = 'now', int $nth = 0, bool $allowCurrentDate = false, $timeZone = null): DateTime
```

### Parameters
- **$currentTime** (string | \DateTime | \DateTimeImmutable) - Optional - Relative date: 'now', a date string (via `new DateTime(...)`), or a DateTimeInterface
- **$nth** (int) - Optional - Matches to skip: 0 returns the current date/time if it is a match; 1 skips the first match; etc.
- **$allowCurrentDate** (bool) - Optional - true returns the current date if it exactly matches the expression
- **$timeZone** (?string) - Optional - IANA name (e.g. 'Asia/Tokyo'); overrides the $currentTime timezone or the system default

### Returns
- **\DateTime** - The next matching date

### Throws
- **\RuntimeException** - 'Impossible CRON expression' after maxIterationCount iterations

### Example
```php
$cron = new CronExpression('@daily');
echo $cron->getNextRunDate()->format('Y-m-d H:i:s');
echo $cron->getNextRunDate(null, 2)->format('Y-m-d H:i:s');      // 2 matches ahead
echo $cron->getNextRunDate('2010-01-12 00:00:00', 0, false, 'America/New_York')->format('Y-m-d H:i:s');
```

### Error Example
```php
try {
    $cron = new CronExpression('0 0 30 2 *');
    $cron->getNextRunDate(); // no such date exists
} catch (RuntimeException $e) {
    // 'Impossible CRON expression'
}
```
```
Tokens:
Raw