Product Decisions This Supports

Testability & Reliability: Enables deterministic testing of time-dependent logic (e.g., expiration checks, scheduled tasks, rate limiting) by replacing DateTimeImmutable with a mockable Clock interface. Critical for CI/CD pipelines and regression testing.
Decoupling Time Logic: Aligns with Clean Architecture principles by abstracting time dependencies, making services easier to swap (e.g., for time travel debugging or timezone adjustments).
Roadmap for Time-Sensitive Features:
- Subscription Services: Test expiration logic for paid tiers without flakiness.
- Event-Driven Systems: Simulate delayed processing or backfilling in event queues.
- Multi-Timezone Support: Standardize timezone handling across microservices (e.g., SystemClock::fromUTC()).
Build vs. Buy: Buy—this is a lightweight, battle-tested abstraction (PSR-20 compliant) with zero maintenance overhead. Avoid reinventing wheel for time mocking.
Use Cases:
- Legacy Refactoring: Gradually replace hardcoded new DateTime() calls in monoliths.
- Feature Flags: Test time-based rollouts (e.g., "disable after 30 days").
- Audit Logs: Replay past events with frozen clocks for compliance checks.

When to Consider This Package

Adopt if:

Your PHP app relies on DateTimeImmutable for business logic (e.g., deadlines, retries, caching).
Test flakiness due to time dependencies (e.g., Time::now() in tests).
You need timezone isolation (e.g., UTC for APIs, local time for UIs).
PHP 8.1+ is your minimum version (or you’re willing to upgrade).
Your team prioritizes maintainability over micro-optimizations (this adds ~50KB to vendor dir).

Look elsewhere if:

You’re using JavaScript/Node.js: Consider jest.useFakeTimers() or luxon.
Performance is critical in time-sensitive paths (e.g., high-frequency trading)—this adds minimal overhead (~1–2ms per call), but direct DateTime is faster.
Your app is procedural with no DI container (though you can still use it manually).
You need historical time adjustments (e.g., "what if this event happened yesterday?"): Pair with a library like lcobucci/clock-adjust or implement custom logic.

For Executives: *"This is a 10-minute fix to eliminate a major source of test flakiness. By abstracting time behind an interface, we can:

Ship features faster: No more ‘works on my machine’ bugs from time zones or clock skew.
Reduce tech debt: Replace spaghetti date('Y-m-d') calls with a single, testable source of truth.
Future-proof: Aligns with PSR-20 (PHP’s emerging standard for time), ensuring compatibility with upcoming frameworks like Laravel 11+. Cost: Zero. It’s a drop-in replacement for DateTimeImmutable with zero runtime impact in production."*

For Engineers: *"This is the gold standard for time mocking in PHP. Key wins:

Zero flaky tests: Replace Time::now() with FrozenClock for reproducible tests.
PSR-20 compliant: Future-proof for PHP’s evolving standards (e.g., ClockInterface).
Lightweight: ~50KB, no dependencies, and immutable by design (no accidental state changes).
Battle-tested: Used in Laravel, Symfony, and other major ecosystems. Migration path:

// Before (flaky)
if ($user->expiresAt > new DateTimeImmutable()) { ... }

// After (testable)
if ($user->expiresAt > $clock->now()) { ... }

Tradeoff: Minimal boilerplate for 100% test reliability."*