Chronos Laravel Package

Product Decisions This Supports

• Domain modeling decisions. Chronos forces an explicit choice between three types — Chronos (an instant with timezone), ChronosDate (calendar date, time frozen at 00:00:00), and ChronosTime (wall-clock time, no date). That distinction is a product decision, not a technical one: a birthday, a delivery window, and a billing timestamp fail in different ways and should not share a type. This package makes the correct model the path of least resistance.
• Correctness requirements for anything date-sensitive. Features like subscription renewals, trial expiry, invoice periods, booking slots, SLAs, and reporting cutoffs all hinge on arithmetic that survives DST transitions. addElapsedHours/Minutes/Seconds (true inverses of diffIn*) gives us a defensible answer to "is an hour always an hour?" without hand-rolled timestamp math.
• Testability as a shippable requirement. setTestNow() and the newer scoped withTestNow() let us specify and demo time-dependent behavior deterministically ("what does the customer see on day 30?"). This is a product-quality lever: it reduces flaky tests that block releases and makes edge-case acceptance criteria actually verifiable before launch.
• Architecture seam for time. ClockFactory implements PSR-20, so "what time is it?" becomes an injected dependency. Adopting it early is cheap; retrofitting it into a mature codebase after a timezone incident is not.
• Roadmap enablement. Recurring schedules, business hours, occurrence logic (nextOccurrenceOf, previousOccurrenceOf, startOfHour/endOfHour), and scoped time mocking map directly onto calendar/booking/scheduling roadmap items. It reduces bespoke date utility code we would otherwise own and maintain.
• Build vs. buy. Buy. Date arithmetic is commodity logic with disproportionately sharp edges (DST, leap years, ISO weeks, microsecond precision). There is no product differentiation in writing it ourselves, and a maintained MIT library removes an entire category of self-inflicted defects.
• Prioritization input. If the next two quarters are light on time semantics, this decision can wait. If scheduling, billing, or reporting is core, this is a low-cost foundational bet worth making now — before the code that would need migrating exists.

When to Consider This Package

Good fit when:

• You are building PHP services where date/time semantics are load-bearing: bookings, recurring events, billing cycles, availability windows, SLAs, or fiscal/calendar reporting.
• You want immutability as an enforced invariant rather than a style guideline, and the current codebase passes mutable DateTime objects around by reference.
• You need date-only and time-only types that cannot silently acquire an accidental timezone offset.
• Your tests need a controllable "now" and you want it scoped rather than global.
• You can absorb a small number of adapters at system boundaries and are willing to pin the PHP version per the project's version map.
• You value a maintained release cadence and MIT licensing with no procurement friction.

Look elsewhere or defer when:

• You are a Laravel shop already standardized on Carbon. Carbon 3 offers immutable classes and most of the ergonomics. Migrating an existing Carbon-heavy codebase to Chronos buys marginal benefit against real churn. Treat this as "consider for new code," not "rewrite."
• Your boundary surface type-hints DateTimeInterface. In 3.x, Chronos no longer extends DateTimeImmutable or implements DateTimeInterface, and ChronosDate deliberately does not share types with Chronos. ORMs, serializers, API schema generators, and third-party SDKs that demand native datetime types will need adapters. Spike that interop surface before committing.
• Ecosystem gravity and hiring matter more than design purity. Carbon's ubiquity means more answers, more prior experience, and fewer surprises for new hires. Chronos is framework-adjacent (CakePHP) even though it is framework-agnostic; the "0 dependents" figure in the metadata should be verified independently rather than treated as an adoption verdict, but it does argue for doing your own due diligence.
• You need a library that is also the JS-side answer. Nothing here solves the PHP/JS time split; that remains a separate decision.
• Your risk posture demands a large, non-framework-adjacent maintainer base. Choose Carbon for the network effect and accept the trade-offs.

How to Pitch It (Stakeholders)

To executives: This is a small, MIT-licensed, actively maintained date/time library with no license cost, no vendor lock-in, and no infrastructure footprint — one Composer dependency. The business case is defect prevention, not features: it structurally removes a recurring class of production bugs where dates shift by a day, timestamps mutate unexpectedly, or elapsed-time calculations go wrong across daylight-saving transitions. Those bugs are expensive precisely because they are rare, hard to reproduce, and often surface in billing, scheduling, or compliance reporting. The one honest caution is that it is not a drop-in replacement for PHP's native datetime interface, so we would wrap it behind our own interfaces — which is the right architecture regardless of which library we pick.

To engineering: Immutable by default, so modification bugs disappear. Three explicit types eliminate the date-vs-instant conflation that causes "birthday renders a day early" and "midnight UTC rolls back a date." A first-class test clock with scoped mocking removes the flaky, sleep-based tests that block CI. PSR-20 ClockFactory gives a clean injection seam. DST-safe elapsed arithmetic is provided as the true inverse of the diff methods, so we stop hand-rolling Unix-timestamp math. Costs are real and bounded: we do not get DateTimeInterface in 3.x, so we write adapters at ORM and serialization boundaries, we pin PHP versions per the version map, and we follow the documented 2.x→3.x deprecation path rather than jumping majors.

Proposed ask: approve a timeboxed pilot — one bounded, date-heavy area (scheduling or billing period logic), one to two sprints, with explicit success criteria: reduction in date-related defects, reduction in time-dependent test flakiness, and lines of bespoke date utility code deleted. Adopt as the standard for new domain code only; no retrofit mandate until the pilot reports.