Clock Laravel Package

Technical Evaluation

Architecture fit. The underlying pattern—injecting a Clock abstraction instead of calling now(), Carbon::now(), or Date::now() directly—is a legitimate, low-coupling design that fits Laravel's container cleanly. It makes time a seam you can control in tests and reason about in domain code (expiry, scheduling, TTL, rate windows). The architectural value here is the interface discipline, not the package: this is a 2–4 class surface (an interface, a system clock, a test double, and a provider) that costs roughly a day to write internally. Assess the pattern, not the artifact.

Integration feasibility. Technically trivial: composer require rikudou/clock, provider registration, one interface binding. No native extensions, no external services, no queue/HTTP surface. The real integration cost sits entirely in the call-site refactor, not the dependency.

Technical risk. High relative to value delivered:

• Bus factor / validation signal. 1 star, 0 dependents, score 0.005. There is no downstream usage acting as a compatibility canary, no community to surface breakage, and no evident release cadence. Assume you will own this code from day one.
• Standards divergence. PSR-20 (Psr\Clock\ClockInterface, now(): DateTimeImmutable) and Symfony\Component\Clock already solve this with maintenance and a MockClock. If this package predates or diverges from PSR-20, you are adopting a private dialect for a problem the ecosystem has standardized.
• Immutability and timezone semantics. Unverified whether the clock returns DateTimeImmutable or mutable DateTime, and whether it normalizes to UTC. Mutable returns reintroduce the exact aliasing bugs the pattern is meant to eliminate.
• Global state coupling. The dangerous failure mode is a clock that internally wraps Carbon::setTestNow(), which mutates process-global state and leaks across tests. Explicit DI is safe; a global hijack is not.
• Laravel version drift. Composer constraints on illuminate/support and PHP floor determine shelf life. With no maintainer activity, a future Laravel/PHP bump strands you on a fork.

Key questions to resolve before a decision.

1. Does it implement PSR-20, or a bespoke interface?
2. Does now() return DateTimeImmutable? Is timezone handling explicit (UTC) or inherited from date_default_timezone_set?
3. Is there a frozen/offset test double, and can it be reset between tests?
4. Does it mutate Carbon global state, or is it purely explicit?
5. What are the PHP and illuminate/* constraints, and when was the last commit?
6. Is there test coverage and CI, or is the README the only documentation?
7. Does the service provider auto-discover, and is the binding a singleton (shared state across a request) or transient?
8. How many call sites in our codebase would need to change for this to deliver any value?

Integration Approach

Stack fit. Suitable for a Laravel 9+ / PHP 8.1+ service codebase where constructor injection is already the norm. It fits poorly as a bolt-on to a legacy codebase that reads wall-clock time in dozens of controllers and models—there the package adds a dependency without changing behavior, and the refactor becomes the whole project.

Alternatives worth weighing first. Given zero dependents, the default recommendation is not to adopt rikudou/clock as a runtime dependency. Ranked options:

1. symfony/clock — PSR-20 compliant, actively maintained, ships MockClock and ClockSensitiveTrait. Best if we want a supported dependency.
2. PSR-20 interface + ~40-line internal SystemClock / FrozenClock — zero third-party risk, full control, MIT-compatible reading of the source for reference.
3. Adopt rikudou/clock behind an adapter — only if it demonstrably implements PSR-20 and returns immutable UTC; wrap it so the package type never leaks into domain signatures.

Compatibility checks. Confirm auto-discovery via extra.laravel.providers, the illuminate/support version range against our pinned Laravel, and whether the provider registers a singleton (document the shared-state implication). Verify it does not interfere with Carbon::setTestNow() used by existing tests.

Migration path and sequencing.

1. Audit — static scan for now(), Carbon::now(), new DateTime, time(), Date::now(); rank by business criticality (billing, expiry, scheduling first).
2. Define the seam — introduce PSR-20 ClockInterface in our own container config; bind SystemClock in production.
3. Refactor incrementally — one service at a time, constructor injection only; no service-locator calls.
4. Test tooling — bind FrozenClock/MockClock in the test case base class with per-test reset to prevent leakage.
5. Conventions — lint rule or code review checklist banning direct wall-clock reads in domain code; keep the Date façade tolerated only at the framework boundary.
6. Decide on the package — if a PSR-20 implementation exists and passes the questions above, it can substitute for step 2; otherwise proceed internally and revisit later.

The sequencing matters more than the choice: the interface and the convention deliver the value, and either path is swappable later if domain code depends only on PSR-20.

Operational Impact

Maintenance. Treat this as vendored code. With one star, zero dependents, and no visible security or release process, the expected maintenance burden is "we fork it on the first PHP major." Budget a modest annual cost for dependency review, and prefer an internal implementation that eliminates the fork entirely. MIT licensing makes that copy safe.

Support. No community, no issue-tracker history to mine, no StackOverflow corpus. Onboarding relies on the README plus whatever we write. Mitigate with a short ADR: why the clock seam exists, how to inject it, how to freeze time in tests, and the UTC convention.

Scaling. Runtime cost is negligible—one datetime construction per call. The scaling dimension is organizational: the pattern only pays off if adoption is consistent. A codebase where half the services inject a clock and half call now() is worse than either extreme, because test-time behavior becomes unpredictable. Scaling also implies test-suite growth: a shared frozen clock singleton across a parallel test run is a correctness hazard, so the test double must be per-test, not container-singleton.

Failure modes to design against.

• State leakage — a singleton mock clock retaining a frozen instant across tests, producing order-dependent suites.
• Mutability aliasing — mutable DateTime returns shared by reference, corrupting previously captured timestamps.
• Timezone drift — server-local returns instead of UTC, yielding off-by-hours bugs in expiry and billing that pass in CI and fail in production across regions.
• DST boundaries — wall-clock arithmetic across transitions; require explicit timezone handling in tests.
• Silent abandonment — a PHP or Laravel upgrade breaking the composer constraint with no upstream fix, forcing an emergency fork under release pressure.
• Global hijack — a clock that mutates Carbon process state interfering with unrelated test tooling or libraries that read Carbon::now().

Ramp-up. Learning the abstraction is a few hours for any mid-level engineer. The genuine cost is the call-site refactor and the review discipline to keep it from eroding—realistically one to two engineer-weeks spread across a mid-sized service, with ongoing review vigilance.

Verdict. The pattern is right; the package is not a defensible dependency at 1 star and zero dependents. Adopt PSR-20 plus a small internal implementation, or symfony/clock if a supported third-party is preferred, and use this repository at most as a reference implementation behind an adapter.