CakePHP Chronos

Chronos is a standalone PHP date/time library, originally forked from Carbon but since diverged into its own API, maintained by the CakePHP team. It provides immutable-by-default Chronos/ChronosDate/ChronosTime value objects alongside mutable variants, plus ChronosInterval and ChronosPeriod/ChronosDatePeriod for representing durations and recurring date ranges. It implements the PSR-20 clock interface (psr/clock), making it usable as a testable, injectable clock source in any PHP application.

What You Get

• Immutable Chronos, ChronosDate, and ChronosTime classes, with mutable counterparts available when needed
• ChronosInterval for representing durations and ChronosPeriod/ChronosDatePeriod for iterating recurring date ranges
• A DifferenceFormatter for human-readable relative time strings (e.g. “2 hours ago”)
• PSR-20 clock interface support (psr/clock-implementation) via ClockFactory, enabling testable, injectable time sources
• Built-in translation support (Translator) for localized date/time formatting

Common Use Cases

• Replacing native PHP DateTime usage with immutable objects to eliminate accidental-mutation bugs in business logic
• Injecting a PSR-20 clock into services for deterministic, testable time-dependent code
• Computing and formatting durations between two dates for display (e.g. “3 days ago”)
• Iterating recurring date ranges (e.g. billing cycles, recurring events) with ChronosPeriod

Under The Hood

Architecture - The library is organized around a small set of focused value-object classes in src/: Chronos.php (immutable datetime), ChronosDate.php (date-only), ChronosTime.php (time-of-day), ChronosInterval.php (durations), and ChronosPeriod.php/ChronosDatePeriod.php (recurring ranges), with shared formatting logic factored into FormattingTrait.php and locale handling isolated in Translator.php; ClockFactory.php implements the PSR-20 ClockInterface to make the current time swappable in tests. Tech Stack - Modern PHP (>=8.1) with a single runtime dependency, psr/clock, managed via Composer, with dev tooling covering PHPUnit, PHPStan (via Phive-installed tooling), Rector, and the CakePHP coding-standard PHP_CodeSniffer ruleset. Code Quality - The tests/TestCase/ directory has dedicated suites per class (ChronosTimeTest.php, ChronosIntervalTest.php, ChronosPeriodTest.php, ClockFactoryTest.php, plus nested DateTime/ and Date/ subdirectories for deeper coverage), run via composer test, composer stan, and composer cs-check in CI, and a tests/Benchmark/ directory tracks performance via phpbench.json. API Design - Chronos deliberately abandoned extending PHP’s native DateTime/DateTimeImmutable classes (an explicit divergence from its Carbon origins, documented in the README) in favor of a self-contained API, trading some drop-in compatibility for a cleaner immutable-object contract that avoids surprising mutation-inheritance behavior.