Clock Laravel Package

Getting Started

1. Install the package via Composer:

   composer require lcobucci/clock
   

2. Define a domain service that uses time — e.g., an OrderService that sets a placedAt timestamp:

   use Lcobucci\Clock\Clock;
   use Lcobucci\Clock\ClockInterface;
   
   class OrderService
   {
       private ClockInterface $clock;
   
       public function __construct(ClockInterface $clock)
       {
           $this->clock = $clock;
       }
   
       public function placeOrder(): void
       {
           $now = $this->clock->now();
           // persist with $now
       }
   }
   

3. Bind the clock in Laravel’s service container — typically in AppServiceProvider:

   $this->app->bind(ClockInterface::class, SystemClock::class);
   

4. Use in tests by swapping to a fixed/frozen clock:

   use Lcobucci\Clock\FrozenClock;
   
   $clock = new FrozenClock(new DateTimeImmutable('2024-01-01 12:00:00'));
   $this->app->instance(ClockInterface::class, $clock);
   

Implementation Patterns

• Domain-Centric Design: Inject ClockInterface into services, repositories, or Value Objects that rely on current time — never call new DateTimeImmutable() or time() directly inside business logic.
• Testing with Determinism:
  • Use FrozenClock to lock time at a known moment for precise assertions.
  • Use FixedClock if you want time to advance (e.g., new FixedClock(new DateTimeImmutable(), '+1 second')).
  • Combine with Laravel’s DatabaseTransaction, RefreshDatabase, or DatabaseMigrations for clean test isolation.
• Framework Integration:
  • Bind ClockInterface to SystemClock in production service provider.
  • Override via app()->instance() or custom test setup in feature/integration tests.
• Middleware for Time Control (optional advanced pattern):

  // In tests: hijack request handling to freeze time
  public function withFrozenClock(DateTimeImmutable $time, callable $callback): mixed
  {
      $this->app->instance(ClockInterface::class, new FrozenClock($time));
      return $callback();
  }
  

Gotchas and Tips

• SystemClock is stateless and thread-safe — but not mockable with Mockery::mock() directly. Use createMock(ClockInterface::class) instead, or prefer Faker + instance() injection in tests.
• Test flakiness often comes from implicit time usage — search for time(), date(), new DateTimeImmutable(), and replace them all.
• Configuration edge case: Laravel’s config('app.timezone') isn’t automatically applied by SystemClock. Ensure all your DateTimeImmutable instances use UTC (best practice) or explicitly set timezone in your clock usage if needed (though lcobucci/clock defaults to UTC for consistency).
• Extensibility: Implement ClockInterface yourself for custom behaviors (e.g., clock that advances time in sync with application events).
• Performance: ClockInterface calls add negligible overhead — prefer correctness and testability over micro-optimizing time lookups.