README

Evaluate whether a recurring rule string is due on a given date. Pure PHP 8.2+, no framework dependencies.

Installation

composer require antnavdev/recurrence

Usage

use AntNavDev\Recurrence\Recurrence;
use Carbon\Carbon;

$recurrence = new Recurrence('weekly:mon,wed,fri');
$recurrence->isDueOn(Carbon::parse('2026-04-13')); // Monday → true
$recurrence->isDueOn(Carbon::parse('2026-04-14')); // Tuesday → false

For rules that require an anchor date (biweekly and interval), pass it as the second constructor argument:

$recurrence = new Recurrence('biweekly:mon', anchorDate: Carbon::parse('2025-01-06'));
$recurrence->isDueOn(Carbon::parse('2025-01-06')); // week 0 → true
$recurrence->isDueOn(Carbon::parse('2025-01-13')); // week 1 → false
$recurrence->isDueOn(Carbon::parse('2025-01-20')); // week 2 → true

$recurrence = new Recurrence('interval:7', anchorDate: Carbon::parse('2025-01-01'));
$recurrence->isDueOn(Carbon::parse('2025-01-01')); // day 0 → true
$recurrence->isDueOn(Carbon::parse('2025-01-08')); // day 7 → true
$recurrence->isDueOn(Carbon::parse('2025-01-09')); // day 8 → false

Rule format

Valid day-of-week codes: mon, tue, wed, thu, fri, sat, sun.

Exceptions

• AntNavDev\Recurrence\InvalidRuleException (extends \InvalidArgumentException) — thrown when the rule string cannot be parsed (e.g. whenever:tuesday, monthly:foo).
• \LogicException — thrown when isDueOn() is called with a biweekly or interval rule but no anchorDate was provided.

Running tests

composer install
./vendor/bin/phpunit