PHPackages                             php-alchemist/chrono-smith - 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. php-alchemist/chrono-smith

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

php-alchemist/chrono-smith
==========================

A reusable, deterministic Scheduling Engine for PHP.

v1.0.0-rc(1mo ago)013[1 issues](https://github.com/PHP-Alchemist/ChronoSmith/issues)MITPHPPHP >=8.4CI passing

Since May 1Pushed 1mo agoCompare

[ Source](https://github.com/PHP-Alchemist/ChronoSmith)[ Packagist](https://packagist.org/packages/php-alchemist/chrono-smith)[ RSS](/packages/php-alchemist-chrono-smith/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (1)Dependencies (5)Versions (2)Used By (0)

ChronoSmith
===========

[](#chronosmith)

ChronoSmith is a reusable, deterministic scheduling engine for PHP 8.4+. It models recurring obligations with a compact, versioned DSL (`CS=1`) and separates schedule intent from mutable schedule progress.

The engine is domain-agnostic: it computes schedule dates, records progress, and derives status such as overdue without knowing anything about billing, memberships, reminders, jobs, or any other application domain.

Installation
------------

[](#installation)

```
composer require php-alchemist/chrono-smith
```

Core Concepts
-------------

[](#core-concepts)

- **Schedule Definition**: Mostly immutable recurrence intent: start date, interval, anchor, roll policy, stickiness, due mode, end date, occurrence limits, timezone metadata, grace period, namespace, and opaque metadata.
- **Schedule State**: Mutable progress through obligations: `cursor`, `last`, `next`, and `rem`.
- **Cursor Stability**: Advancement is based on the scheduled due date (`cursor`), not the actual occurrence date (`last`). Early or late completion does not cause anchor drift.
- **Derived Overdue Status**: Overdue is never stored. It is derived at runtime with `now > next + grace`.
- **Versioned Codec**: DSL hydration and serialization are handled by versioned codecs using read-old/write-latest semantics.

DSL Example
-----------

[](#dsl-example)

```
[CS=1;ns=App\Scheduling\BillingScheduler;s=@2026-01-30;i=1m;a=dom30;r=back;stick=dom;cursor=@2026-01-30;next=@2026-02-28]

```

Important fields:

- `s`: start date, written as `@YYYY-MM-DD`
- `i`: interval, such as `1d`, `1w`, or `1m`
- `a`: optional anchor, such as `dowFRI`, `dom30`, or `eom`
- `r`: monthly roll policy, `back` or `forward`
- `stick`: monthly stickiness, `dom` or `eom`
- `mode`: due semantics, `on` or `by`
- `n` / `rem`: max and remaining occurrences
- `e`: end date; no occurrences after this date
- `gr`: grace period used by overdue derivation
- `ns`: PHP-style namespace/class-name metadata, preserved exactly
- `meta64`: opaque base64url metadata

Quick Start
-----------

[](#quick-start)

```