Clock Laravel Package

Product Decisions This Supports

• Testability & Reliability: Enables deterministic time-based logic in tests by replacing new DateTimeImmutable() with dependency-injected clocks (e.g., FrozenClock). Eliminates flaky tests caused by real-time dependencies.
• Time-Zone Isolation: Decouples business logic from system time zones, allowing consistent behavior across deployments (e.g., SystemClock::fromUTC()).
• PSR-20 Compliance: Aligns with the emerging PSR-20 Clock Interface, reducing future refactoring costs.
• Roadmap for Time-Sensitive Features:
  • Expiration Systems: E.g., "Filter expired subscriptions" (as in the example).
  • Scheduled Jobs: Replace now() calls in cron-like logic with injectable clocks.
  • Audit Logs: Timestamp events consistently in tests vs. production.
• Build vs. Buy: Buy—this is a lightweight (~1KB), battle-tested abstraction with no maintenance overhead. Avoid reinventing wheel for time decoupling.
• Use Cases:
  • E-commerce: Test "flash sale" expiration logic.
  • Finance: Validate time-sensitive transactions (e.g., "settle by 5 PM UTC").
  • IoT/Edge: Simulate time offsets for device synchronization tests.

When to Consider This Package

Adopt if:

• Your PHP app uses new DateTimeImmutable() or time() directly in business logic.
• Tests fail intermittently due to time-based conditions (e.g., "expired in 5 seconds").
• You need to mock time for time-sensitive workflows (e.g., payments, subscriptions, alerts).
• Your team follows dependency injection and PSR standards.
• You’re on PHP 8.2+ (minimum requirement; PHP 8.4+ recommended for latest features).

Look elsewhere if:

• You’re using Laravel’s built-in Carbon and already leverage its freezeTime() or shouldReceive() methods (though lcobucci/clock offers a more generic solution).
• Your app is time-insensitive (e.g., static content sites).
• You’re on PHP < 8.2 (consider a polyfill or upgrade path).
• You need advanced time calculations (e.g., business hours, daylight saving adjustments)—combine with libraries like spatie/temporal.
• Your team prefers Ruby’s Timecop or Java’s Clock patterns—this is PHP-specific.

How to Pitch It (Stakeholders)

For Executives: *"This package lets us write unbreakable time-sensitive logic—like expiration checks or scheduled jobs—without flaky tests. By injecting a 'clock' instead of using new DateTime(), we can:

• Freeze time in tests to simulate edge cases (e.g., 'What if a payment expires at midnight?').
• Isolate time zones so deployments in different regions behave consistently.
• Future-proof our code with PSR-20 compliance, avoiding refactors when PHP updates time handling. It’s a zero-maintenance, 5-minute upgrade that eliminates a common source of bugs in time-critical systems."*

For Engineers: *"Replace new DateTimeImmutable() with Clock interface:

• Production: Use SystemClock (e.g., SystemClock::fromUTC()).
• Tests: Use FrozenClock with fixed timestamps (e.g., FrozenClock::fromUTC('2023-01-01')). Benefits:
• No more sleep(1) hacks in tests.
• PSR-20 ready—future-proof for PHP’s clock RFC.
• Lightweight (~1KB, no DB or external deps). Example:

// Before (brittle)
if (new DateTimeImmutable() > $expiry) { ... }

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

Migration path: Start with critical time-sensitive services (e.g., payments, subscriptions)."*

For QA/Testers: *"This lets you reproduce time-based bugs deterministically. No more:

• 'It worked yesterday!'
• 'The test passed on my machine.' Instead, freeze time to test:
• Exactly when a subscription expires.
• Edge cases like DST transitions.
• Race conditions in scheduled jobs. Example:

$clock = new FrozenClock(new DateTimeImmutable('2023-12-31 23:59:59'));
// Now tests always run at 'Dec 31, 2023'—no surprises!"*