Clock Laravel Package

Getting Started

Start by installing via Composer: composer require beste/clock. This package provides immutable ClockInterface implementations—primarily SystemClock, FrozenClock, and MockClock—to abstract time-related operations in your application. The core use case is injecting clock dependencies instead of calling date(), time(), or Carbon::now() directly, enabling better testability and control over time in business logic. First, bind a clock implementation in your service container (e.g., SystemClock for production, FrozenClock for tests), then type-hint ClockInterface in services, commands, or domain services.

Implementation Patterns

• Domain Layer Integration: Inject ClockInterface into value objects, aggregates, or domain services to determine current time for timestamps, expiry calculations, or scheduling without side effects.
• Testing: Use FrozenClock with a fixed DateTimeImmutable in unit tests (e.g., $clock = new FrozenClock(new DateTimeImmutable('2022-01-01'))), or MockClock (if available) for advanced assertions on time progression.
• Laravel Integration: Register a binding like ClockInterface::class => fn() => new SystemClock() in AppServiceProvider. Override in phpunit.xml or feature test setups with FrozenClock for deterministic test runs.
• Timezones: Pair with \DateTimeZone when constructing clocks to handle localized time logically (e.g., new SystemClock(new \DateTimeZone('UTC'))), especially for cron jobs or multi-region apps.

Gotchas and Tips

• Immutability is key: Clock objects return new instances when advancing time (if supported by the implementation); always use the returned clock for time progression steps to avoid state leaks.
• No built-in drift or progression: Unlike some test-time tools (e.g., Carbon’s test helpers), this package is minimal—FrozenClock stays static unless manually advanced via withTime(). For advancing time automatically (e.g., ++$clock), wrap it or create a test helper.
• PHPStan/IDE support: Add @method \DateTimeImmutable now() via @mixin or stubs if autocompletion breaks; the interface is sparse by design.
• Extensibility: Implement your own ClockInterface (e.g., NtpClock for sync with NTP servers or AppClock with app-specific defaults), then bind it conditionally (e.g., in local vs prod environments).
• Check release age: With last release in late 2022, verify maintained compatibility with newer PHP versions or Laravel releases before committing long-term. Consider forks if active maintenance is required.