PHPackages                             nephifey/cron-expression - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. nephifey/cron-expression

ActiveLibrary[Utility & Helpers](/categories/utility)

nephifey/cron-expression
========================

Cron expression parser to get the previous run date, next run date, and determine if the expression is due to run based on the next run date.

v1.0.0(2y ago)0772↑116.7%GPL-3.0-or-laterPHPPHP >=7.4

Since Mar 28Pushed 2y ago1 watchersCompare

[ Source](https://github.com/nephifey/cron-expression)[ Packagist](https://packagist.org/packages/nephifey/cron-expression)[ Docs](https://github.com/nephifey/cron-expression)[ RSS](/packages/nephifey-cron-expression/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (3)Dependencies (1)Versions (4)Used By (0)

cron-expression
===============

[](#cron-expression)

Cron expression parser to get the previous run date, next run date, and determine if the expression is due to run based on the next run date. This implementation supports the minute, hour, day of the month, month, and day of the week attributes and only supports a limited amount of non-standard characters/macros, see the [Cron Expression Format](#cron-expression-format) below.

### Cron Expression Format:

[](#cron-expression-format)

Refer to the [Cron Wikipedia Page](https://en.wikipedia.org/wiki/Cron) if desired, which is where most this content is from, but keep in mind this library doesn't support everything documented within there.

```
# ┌───────────── minute (0–59)
# │ ┌───────────── hour (0–23)
# │ │ ┌───────────── day of the month (1–31)
# │ │ │ ┌───────────── month (1–12)
# │ │ │ │ ┌───────────── day of the week (0–6) (Sunday to Saturday;
# │ │ │ │ │                                   7 is also Sunday on some systems)
# │ │ │ │ │
# │ │ │ │ │
# * * * * *
```

**Supported Characters:**

CharacterDescriptionExample ExpressionAsterisk `*`Equivalent to "all" or the entire allowed range of values.`* * * * *`Comma `,`Comma separated value list for scheduling multiple different times.`3,57 * * * SUN,MON`Hyphen `-`Used to specify a range of values for scheduling multiple different times.`* * * * TUE-SAT`Slash `/`Used to specify stepped values throughout the allowed range of values.`*/5 * * * *`Numeric (or) Non-standard LiteralSchedule using a specific number within the allowed range of values.`5 * * * *`**Supported Non-standard Literals:**

AttributeLiteralMapped NumericmonthJAN1monthFEB2monthMAR3monthAPR4monthMAY5monthJUN6monthJUL7monthAUG8monthSEP9monthOCT10monthNOV11monthDEC12day of the weekSUN0day of the weekMON1day of the weekTUE2day of the weekWED3day of the weekTHU4day of the weekFRI5day of the weekSAT6day of the week70**Supported Non-standard Macros:**

MacroDescriptionMapped Expression`@yearly`Run once a year at midnight of 1 January`0 0 1 1 *``@annually`Run once a year at midnight of 1 January`0 0 1 1 *``@monthly`Run once a month at midnight of the first day of the month`0 0 1 1 *``@weekly`Run once a week at midnight on Sunday`0 0 1 1 *``@daily`Run once a day at midnight`0 0 1 1 *``@midnight`Run once a day at midnight`0 0 1 1 *``@hourly`Run once an hour at the beginning of the hour`0 0 1 1 *`Getting Started
---------------

[](#getting-started)

Install the package into your project using composer via the command below.

```
composer require nephifey/cron-expression

```

Usage
-----

[](#usage)

### Basic Example

[](#basic-example)

Parse cron expressions and get the previous run date, next run date, or check if the expression is due.

```
require_once "vendor/autoload.php";

$parser = new \CronExpression\Parser();
$expression = $parser->parse("* * * * *");

$isDue = $expression->isDue();
$nextDateFormatted = $expression->getNextRunDate()->format("Y-m-d H:i:s");
$prevDateFormatted = $expression->getPrevRunDate()->format("Y-m-d H:i:s");

echo "Is Due: " . ($isDue ? "Yes" : "No") . "\r\n";
echo "Next Date: {$nextDateFormatted}\r\n";
echo "Prev Date: {$prevDateFormatted}\r\n";

if ($expression->isDue()) {
    echo "-- Run important code here --\r\n";
}
```

### Scheduler Example

[](#scheduler-example)

Use as a crontab alternative to keep expressions within the codebase or database.

**Crontab Setup:**

```
* * * * * apache php crontab.php > /dev/null 2>&1

```

**Codebase Setup:**

```
# crontab.php
require_once "vendor/autoload.php";

$jobs = [
    "* * * * *" => [
        function () { echo "-- Run important code here every minute --\r\n"; },
        function () { echo "-- Run important code here every minute #2 --\r\n"; },
    ],
    "*/5 * * * *" => [
        function () { echo "-- Run important code here every five minutes --\r\n"; },
    ],
];

foreach ($jobs as $expression => $callables) {
    $parser = $parser ?? new \CronExpression\Parser();
    if ($parser->parse($expression)->isDue())
        $combinedCallables = array_merge(($combinedCallables ?? []), $callables);
}

foreach (($combinedCallables ?? []) as $callable) {
    call_user_func($callable);
}
```

### Additional Examples

[](#additional-examples)

You can pass a custom datetime to the isDue method instead of the current datetime/timezone. Additionally, you can enable strict mode, so then it must match the exact datetime/timezone.

```
require_once "vendor/autoload.php";

$parser = new \CronExpression\Parser();
$expression = $parser->parse("* * * * *", new DateTime("now", new DateTimeZone("America/Chicago")));

$isDue = $expression->isDue();
echo "Is Due: " . ($isDue ? "Yes" : "No") . "\r\n"; // Yes

$isDue = $expression->isDue(new DateTime("now", new DateTimeZone("America/New_York")));
echo "Is Due: " . ($isDue ? "Yes" : "No") . "\r\n"; // Yes

$isDue = $expression->isDue(new DateTime("now", new DateTimeZone("America/New_York")), true);
echo "Is Due: " . ($isDue ? "Yes" : "No") . "\r\n"; // No
```

You can reparse cron expressions directly on the expression object based on a new datetime/timezone later on. This can be done in a mutable or immutable way depending on your need.

```
require_once __DIR__ . "/vendor/autoload.php";

$parser = new \CronExpression\Parser();
$expression = $parser->parse("* * * * *", new DateTime("now", new DateTimeZone("America/Chicago")));

echo "{$expression->getNextRunDate()->format("Y-m-d H:i:s")}\r\n"; // current time

$expression->reparse(new DateTime("now +1 minute", new DateTimeZone("America/Chicago")));

echo "{$expression->getNextRunDate()->format("Y-m-d H:i:s")}\r\n"; // one minute ahead

$newExpression = $expression->reparseImmutable(new DateTime("now +2 minute", new DateTimeZone("America/Chicago")));

echo "{$expression->getNextRunDate()->format("Y-m-d H:i:s")}\r\n"; // one minute ahead
echo "{$newExpression->getNextRunDate()->format("Y-m-d H:i:s")}\r\n"; // two minutes ahead
```

###  Health Score

24

—

LowBetter than 32% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity18

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity43

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

3

Last Release

780d ago

PHP version history (2 changes)v1.0.0-alphaPHP ^8.3

v1.0.0PHP >=7.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/ddf96a12b17cf233d09292a2a08fef9de35cd6daa4078132c9b7a529f72c5cb9?d=identicon)[nephifey](/maintainers/nephifey)

---

Top Contributors

[![nephifey](https://avatars.githubusercontent.com/u/46578407?v=4)](https://github.com/nephifey "nephifey (13 commits)")

---

Tags

schedulercronexpression

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/nephifey-cron-expression/health.svg)

```
[![Health](https://phpackages.com/badges/nephifey-cron-expression/health.svg)](https://phpackages.com/packages/nephifey-cron-expression)
```

###  Alternatives

[dragonmantank/cron-expression

CRON for PHP: Calculate the next or previous run date and determine if a CRON expression is due

4.7k474.1M487](/packages/dragonmantank-cron-expression)[lorisleiva/cron-translator

Makes CRON expressions human-readable

3148.5M31](/packages/lorisleiva-cron-translator)[spatie/regex

A sane interface for php's built in preg\_\* functions

1.1k17.1M59](/packages/spatie-regex)[symfony/scheduler

Provides scheduling through Symfony Messenger

8810.8M52](/packages/symfony-scheduler)[rewieer/taskschedulerbundle

Task Scheduler with CRON for Symfony

63242.1k](/packages/rewieer-taskschedulerbundle)[ttree/scheduler

Simple task scheduler for Neos Flow Framework

21108.8k1](/packages/ttree-scheduler)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)