README

PSR-20 Clock implementations for PHP applications. Provides testable time abstractions for domain-driven design and clean architecture.

Features

• PSR-20 compliant - Implements Psr\Clock\ClockInterface
• Testable - FrozenClock for deterministic unit tests
• Timezone-aware - LocalizedClock for specific timezones
• Zero dependencies - Only requires psr/clock
• PHP 7.4+ - Compatible with legacy and modern PHP

Installation

composer require php-architecture-kit/clock

Quick Start

use PhpArchitecture\Clock\SystemClock;
use PhpArchitecture\Clock\FrozenClock;
use PhpArchitecture\Clock\LocalizedClock;

// Production: Use system clock
$clock = new SystemClock();
$now = $clock->now(); // DateTimeImmutable

// Testing: Use frozen clock
$clock = FrozenClock::at(new \DateTimeImmutable('2024-06-15 12:00:00'));
$now = $clock->now(); // Always returns '2024-06-15 12:00:00'

// Timezone-specific: Use localized clock
$clock = new LocalizedClock(new \DateTimeZone('Europe/Warsaw'));
$now = $clock->now(); // DateTimeImmutable in Warsaw timezone

// UTC shortcut
$clock = LocalizedClock::utc();

Clock Implementations

SystemClock

Returns the current system time. Use in production code.

$clock = new SystemClock();
$now = $clock->now(); // Current time

FrozenClock

Returns a fixed time. Ideal for unit testing.

// Freeze at specific time
$clock = FrozenClock::at(new \DateTimeImmutable('2024-01-01 00:00:00'));

// Freeze at current time
$clock = FrozenClock::fromNow();

// Time never changes
$clock->now(); // Always the same
usleep(10000);
$clock->now(); // Still the same

LocalizedClock

Returns current time in a specific timezone.

// Any timezone
$clock = new LocalizedClock(new \DateTimeZone('America/New_York'));

// UTC shortcut
$clock = LocalizedClock::utc();

$now = $clock->now();
echo $now->getTimezone()->getName(); // 'America/New_York' or 'UTC'

Usage in Domain Services

Inject ClockInterface instead of calling new \DateTimeImmutable() directly:

use Psr\Clock\ClockInterface;

class OrderService
{
    public function __construct(
        private ClockInterface $clock
    ) {}

    public function createOrder(array $items): Order
    {
        return new Order(
            items: $items,
            createdAt: $this->clock->now()
        );
    }
}

Production Configuration

// Symfony
services:
    Psr\Clock\ClockInterface:
        class: PhpArchitecture\Clock\SystemClock

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

Testing

class OrderServiceTest extends TestCase
{
    public function testOrderCreatedWithCorrectTimestamp(): void
    {
        $fixedTime = new \DateTimeImmutable('2024-06-15 12:00:00');
        $clock = FrozenClock::at($fixedTime);
        
        $service = new OrderService($clock);
        $order = $service->createOrder(['item1', 'item2']);
        
        $this->assertEquals($fixedTime, $order->getCreatedAt());
    }
}

Comparison

API Reference

SystemClock

FrozenClock

LocalizedClock

Testing

Package is tested with PHPUnit in the php-architecture-kit/workspace project.

License

MIT