Clock Laravel Package

Product Decisions This Supports

• Build vs. buy the time seam. This is not really a "buy" decision — it's six tiny classes over psr/clock (one interface, now(): DateTimeImmutable) under MIT. The real decision is whether to standardize on a PSR-20 clock abstraction at all, and if so whether to spend an afternoon writing it in-house or take a zero-dependency package. Cost of adoption is near-zero; cost of not having decided is unbounded flaky tests in every time-sensitive feature.
• Feature and roadmap bets on time-dependent behavior. Trials and expiries, subscription renewals and proration, scheduled promotions, rate limits and TTLs, "day 7" onboarding emails, aging reports, idempotency windows. Each of these becomes a QA and regression risk proportionate to how hard it is to move the clock. FrozenClock (fixed instant, manually settable) and MinuteClock (collapses sub-minute precision, useful for idempotency keys and "same minute" grouping) directly reduce that risk.
• Test strategy and QA cycle time. FrozenClock::at(...) / ::withNowFrom(...) lets acceptance criteria be written as "given the clock reads 2026-03-01 00:00, when the job runs, then the invoice is prorated." That converts time travel from an engineering hack into a product-testable scenario, which affects how confidently you can promise date-boundary behavior (midnight rollover, DST, leap day, month-end) in a release.
• Multi-region / multi-timezone use cases. UTCClock (storage and inter-service communication — the README's explicit "the clock you should™ use") vs. LocalizedClock::in('Europe/Berlin') (user-facing display and region-specific business rules) is a product-legible distinction, not just a technical one. WrappingClock lets existing legacy objects with a now() method participate without a refactor, which matters for incremental migration scoping.
• Architecture decision: PSR-20 as the seam vs. Carbon's test helpers. Laravel already ships Carbon::setTestNow(). Choosing PSR-20 is a decision to keep business/domain code framework-agnostic and portable, typically because you expect shared libraries, a service extraction, or a non-Laravel consumer. That's a strategic call about coupling, and it should be made deliberately rather than by default.

When to Consider This Package

Consider adopting when:

• You've already decided (or are deciding) to inject a clock rather than call now() / Carbon::now() / date() inside business logic, and you want a standards-based interface (psr/clock) rather than a bespoke one.
• Your time-sensitive rules live in domain services, value objects, or something you intend to publish or share as a package that must not depend on Laravel.
• You want FrozenClock and MinuteClock for free instead of maintaining your own test clock and test helper, and you value a dependency tree that is effectively just psr/clock.
• You need explicit, named timezones bound into specific services (UTCClock for persistence, LocalizedClock for a regional rule engine) rather than relying on the ambient date.timezone.

Look elsewhere (or just implement it) when:

• Your need is application-level test time control. Carbon::setTestNow() / CarbonImmutable::setTestNow() already does this, is battle-tested, and — critically — is respected by framework internals. beste/clock does not touch the scheduler, queue timestamps, cache TTL, or DB NOW(); injecting a FrozenClock into your service does not freeze the world.
• You want a rich mock clock. This package has no MockClock and no notion of time advancing on its own; FrozenClock is static until you call setTo(). If you want sleep()-aware or auto-advancing test clocks with assertion helpers, look at symfony/clock (MockClock, NowPinnedClock), which also has a much larger install base.
• You need framework glue. There is no service provider and no Laravel integration — you bind ClockInterface in AppServiceProvider yourself and override it in test setup. That's two lines, but it's work you own.
• Your project has essentially no time-dependent logic, or you're unwilling to own an unpublished-by-you abstraction for a 75-star, near-zero-dependent package.
• Diligence caveat worth resolving before committing: the provided snapshot shows a 3.x line whose last release is dated 2026-08-23, while a prior internal technical assessment characterized the project as unmaintained since November 2022. Those cannot both be true. Confirm the actual release cadence and PHP/Laravel compatibility directly on Packagist/GitHub rather than trusting either summary. Also note that prior assessments reference a MockClock class that does not exist in this package — a good reminder that the README, not secondhand notes, is the source of truth here.

How to Pitch It (Stakeholders)

To executives: "A small, free, MIT-licensed library that makes time-sensitive features — trials, renewals, expiries, scheduled promotions — deterministic and testable. It lets us validate date-boundary behavior (midnight rollover, month-end, DST) in automated tests instead of hoping, which reduces production incidents and QA cycles on exactly the features that generate revenue. Cost is effectively zero: no license, no vendor, two lines of container configuration. The honest caveat is that the strategic value comes from the pattern (a testable clock), not the library — so read this as 'approve a standard,' not 'approve a vendor.'"

To engineering: "Six thin PSR-20 clock implementations — SystemClock, UTCClock, LocalizedClock, FrozenClock, MinuteClock, WrappingClock. It gives us a clean ClockInterface seam so domain code stops reaching for Carbon::now(), and FrozenClock gives us deterministic tests without hand-rolling a test clock. Dependency tree is essentially just psr/clock; no service provider, so we bind it ourselves in AppServiceProvider and swap to FrozenClock in test setup. Two things to be clear-eyed about: it does not integrate with the scheduler, queue, cache TTLs, or DB time, so Carbon::setTestNow() remains the tool for framework-level test time; and FrozenClock requires manual setTo() — it won't tick. If we want richer mocks with a bigger maintainer base, symfony/clock is the credible alternative. My recommendation is to adopt the PSR-20 interface as our standard and take this package only if we want the implementations for free — with a quick check on release cadence and current PHP/Laravel support before we pin it."