DOCSEARCHbyAlgolia
Submit Docs

dragonmantank/cron-expression

repository·master·Indexed 26 days ago

https://github.com/dragonmantank/cron-expression

A PHP library for parsing CRON expressions to determine if a schedule is due and calculate next or previous run dates. It supports standard CRON syntax, macros (e.g., @daily, @hourly), and advanced scheduling logic such as nearest weekdays (W), last day of month (L), and nth weekdays (#). The Cron\CronExpression class provides methods for validating expressions, managing custom aliases, and retrieving multiple scheduled run dates.

Tokens
1.7K
Snippets
2
Records
15
Agent score
89%

What's inside dragonmantank/cron-expression

  2. Use Cron\CronExpression to parse and calculate schedules

    master

    The Cron\CronExpression class allows you to parse CRON expressions (including macros like @daily), check if a schedule is currently due, and calculate the next or previous run dates. You can also calculate future dates by skipping iterations or calculate dates relative to a specific timestamp.

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

  3. Advanced CRON features for Day of Month and Day of Week

    master

    The parser supports specialized characters for complex scheduling requirements:

    Day of Month

    • Nearest Weekday (W): Finds the nearest weekday (Mon-Fri) to the given day. e.g., * * 15W * *. If the 15th is Saturday, it triggers on Friday the 14th.
    • Last Day of Month (L): e.g., * * L * *.
    • Last Weekday of Month (LW): e.g., * * LW * *.

    Day of Week

    • Nth Day (#): Finds the nth occurrence of a weekday in a month. e.g., * * * * 7#4 targets the 4th Sunday.
    • Last Day of Week (L): Finds the last occurrence of a specific weekday in a month. e.g., * * * * 7L targets the last Sunday.

  5. CRON Expression Syntax and Macros

    master

    A CRON expression consists of five parts: minute (0-59), hour (0-23), day of month (1-31), month (1-12), and day of week (0-7, where Sunday is 0 or 7).

    Supported Syntax

    • Wildcard: * (matches always). ? is an alias for * in day of week and day of month.
    • Lists: , (e.g., 15,30 * * * * for minutes 15 and 30).
    • Ranges: - (e.g., 1-9 * * * * for minutes 1 through 9).
    • Steps: / (e.g., */5 * * * * for every 5th minute).
    • Combinations: e.g., 0-14,30-44 * * * *.

    Macros

    • @yearly or @annually: 0 0 1 1 *
    • @monthly: 0 0 1 * *
    • @weekly: 0 0 * * 0
    • @daily or @midnight: 0 0 * * *
    • @hourly: 0 * * * *

  7. Parse and manage CRON expressions with CronExpression

    master

    The Cron\ CronExpression class is the primary interface for parsing CRON expressions and calculating scheduled run dates. It supports standard CRON parts (minute, hour, day of month, month, day of week) and an optional year. You can instantiate it with a CRON string or use built-in aliases like @daily or @hourly.

  9. Get a cron field instance using FieldFactory

    master

    The FieldFactory class implements a flyweight factory pattern to provide instances of FieldInterface for specific cron expression positions. Use the getField(int $position) method to retrieve a field object. The factory caches instantiated fields to optimize performance.

    Supported positions correspond to the constants defined in CronExpression:

    • CronExpression::MINUTE
    • CronExpression::HOUR
    • CronExpression::DAY
    • CronExpression::MONTH
    • CronExpression::WEEKDAY

    Throws an InvalidArgumentException if the provided position is not a valid cron field position.

  10. Get multiple scheduled run dates

    master

    Use getMultipleRunDates() to retrieve an array of upcoming (or past) scheduled dates.

    Parameters:

    • $total (int): The number of dates to return.
    • $currentTime (string|\DateTimeInterface|null): The starting point.
    • $invert (bool): If true, retrieves previous dates instead of future dates.
    • $allowCurrentDate (bool): If true, includes the $currentTime if it matches.
    • $timeZone (string|null): The timezone to use.

  11. Calculate the previous run date

    master

    Use getPreviousRunDate() to find the most recent time a CRON expression triggered relative to a specific time.

    Parameters:

    • $currentTime (string|\DateTimeInterface): The starting point for calculation (defaults to 'now').
    • $nth (int): Number of matches to skip. 0 returns the immediate previous match.
    • $allowCurrentDate (bool): If true, returns the $currentTime if it matches the expression.
    • $timeZone (string|null): A specific timezone to use for the calculation.