PHPackages                             bakame/cron - 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. [Validation & Sanitization](/categories/validation)
4. /
5. bakame/cron

ActiveLibrary[Validation & Sanitization](/categories/validation)

bakame/cron
===========

CRON for PHP: Validate CRON expression, Calculate run date, determine if a CRON expression is due

0.5.1(4y ago)1312MITPHPPHP ^8.1.0

Since Dec 29Pushed 4y agoCompare

[ Source](https://github.com/bakame-php/cron-expression)[ Packagist](https://packagist.org/packages/bakame/cron)[ GitHub Sponsors](https://github.com/sponsors/nyamsprod)[ RSS](/packages/bakame-cron/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (6)Dependencies (6)Versions (7)Used By (0)

Bakame Cron Expression
======================

[](#bakame-cron-expression)

[![Latest Version](https://camo.githubusercontent.com/a6075c327e34d03a5ae9a931059fdabd028a05c7d48a316805f8496acbbc973c/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652f62616b616d652d7068702f63726f6e2d65787072657373696f6e2e7376673f7374796c653d666c61742d737175617265)](https://github.com/bakame-php/cron-expression/releases)[![Software License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](LICENSE)[![Build](https://github.com/bakame-php/cron-expression/workflows/build/badge.svg)](https://github.com/bakame-php/cron-expression/actions?query=workflow%3A%22build%22)

**NOTE** This is a fork with a major rewrite of  which is in turned a fork of the original  package.

To know more about cron expression your can look at the [Unix documentation](https://www.unix.com/man-page/linux/5/crontab/)

Motivation
----------

[](#motivation)

This package would not exist if the two listed packages were not around. While those packages are well known and used throughout the community I wanted to see if I could present an alternate way of dealing with cron expression.

The reason a fork was created instead of submitting PRs is because the changes to the public API are so important that it would have warranted multiples PR with some passing and other not. Hopefully, some ideas develop here can be re-use in the source packages.

System Requirements
-------------------

[](#system-requirements)

You need **PHP >= 8.1** but the latest stable version of PHP is recommended.

Installing
----------

[](#installing)

### Using composer

[](#using-composer)

Add the dependency to your project:

```
composer require bakame-php/cron
```

### Going solo

[](#going-solo)

You can also use `Bakame\Cron` without using Composer by downloading the library and:

- using any other [PSR-4](http://www.php-fig.org/psr/psr-4/) compatible autoloader.
- using the bundle autoloader script as shown below:

```
require 'path/to/bakame/cron/repo/autoload.php';

use Bakame\Cron\Expression;

Expression::fromString('@daily')->toString(); //display '0 0 * * *'
```

where `path/to/bakame/cron/repo` represents the path where the library was extracted.

Usage
-----

[](#usage)

The following example illustrates some features of the package.

```
use Bakame\Cron\Scheduler;
use Bakame\Cron\Expression;

Expression::registerAlias('@every_half_hour', '*/30 * * * *');

$scheduler = Scheduler::fromSystemTimezone('@every_half_hour');

$scheduler->isDue('2022-03-15 14:30:01'); // returns true
$scheduler->isDue('2022-03-15 14:29:59'); // returns false

$runs = $scheduler->yieldRunsBetween(new DateTime('2019-10-10 23:29:25'), '2019-10-11 01:30:25');
var_export(array_map(
    fn (DateTimeImmutable $d): string => $d->format('Y-m-d H:i:s'),
    iterator_to_array($runs, false)
));
// array (
//   0 => '2019-10-10 23:30:00',
//   1 => '2019-10-11 00:00:00',
//   2 => '2019-10-11 00:30:00',
//   3 => '2019-10-11 01:00:00',
//   4 => '2019-10-11 01:30:00',
// )
```

### Calculating the running time

[](#calculating-the-running-time)

#### Instantiating the Scheduler Immutable Value Object

[](#instantiating-the-scheduler-immutable-value-object)

To determine the next running time for a CRON expression the package uses the `Bakame\Cron\Scheduler` class.
To work as expected this class requires:

- a CRON Expression ( as a string or as a `Expression` object)
- a timezone as a PHP `DateTimeZone` instance or the timezone string name.
- to know if the `startDate` if eligible should be present in the results via a `DatePresence` enum with two values `DatePresence::INCLUDED` and `DatePresence::EXCLUDED`.

To ease instantiating the `Scheduler`, it comes bundle with two named constructors around timezone usage:

- `Scheduler::fromUTC`: instantiate a scheduler using the `UTC` timezone.
- `Scheduler::fromSystemTimezone`: instantiate a scheduler using the underlying system timezone

**Both named constructors exclude by default the start date from the results.**

```