marko/clock

PSR-20 system clock --- inject ClockInterface instead of calling time() so time-dependent code can be tested deterministically. The package binds the standard Psr\Clock\ClockInterface to SystemClock, which reads the system time. There is no Marko-specific clock interface: PSR-20 is already a single explicit method, and depending on it keeps your code compatible with any other PSR-20 clock (Symfony’s or Lcobucci’s, for example). In tests, swap in FakeClock from marko/testing.

Installation

composer require marko/clock

The module binds ClockInterface to SystemClock as a singleton. There is no configuration file.

Usage

Injecting the Clock

Type-hint Psr\Clock\ClockInterface in a constructor and call now() wherever you would have called time() or new DateTimeImmutable():

use DateTimeImmutable;
use Psr\Clock\ClockInterface;

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

    public function expiresAt(): DateTimeImmutable
    {
        return $this->clock->now()->modify('+7 days');
    }

    public function isExpired(Invitation $invitation): bool
    {
        return $invitation->expiresAt < $this->clock->now();
    }
}

For a Unix timestamp, use $this->clock->now()->getTimestamp().

Timezone

By default SystemClock returns times in PHP’s default timezone (date_default_timezone_get()), read each time now() is called. To pin a timezone, construct the clock yourself and bind it in your module:

app/core/module.php

use Marko\Clock\SystemClock;
use Marko\Core\Container\ContainerInterface;
use Psr\Clock\ClockInterface;

return [
    'bindings' => [
        ClockInterface::class => fn (ContainerInterface $container): ClockInterface => new SystemClock('UTC'),
    ],
];

The constructor accepts a DateTimeZone or a timezone name. An unknown name throws DateInvalidTimeZoneException.

You don’t need to pin the clock to get consistent stored times. Entity datetimes and the timestamps Marko packages write to the database (queue jobs, failed jobs, token expiry, notifications, webhook attempts) are converted to the database timezone before they are stored, whatever zone the clock returns.

Testing

Pass a FakeClock wherever the code under test expects a ClockInterface. It is frozen until you move it, so boundaries can be checked exactly:

use Marko\Testing\Fake\FakeClock;

it('expires an invitation after seven days', function (): void {
    $clock = new FakeClock('2026-01-01 12:00:00 UTC');
    $service = new InvitationService($clock);
    $invitation = new Invitation(expiresAt: $service->expiresAt());

    $clock->travel('+7 days');
    expect($service->isExpired($invitation))->toBeFalse();

    $clock->travel('+1 second');
    expect($service->isExpired($invitation))->toBeTrue();
});

Packages Using the Clock

These packages take an injected ClockInterface and so require marko/clock:

• marko/session --- session cookie expiry
• marko/session-file and marko/session-database --- last_activity and garbage collection
• marko/authentication-token --- personal access token expiry checks, and the default expiry and created_at of new tokens
• marko/authentication --- remember-token expiry and remember-cookie expiry
• marko/errors-simple and marko/errors-advanced --- ErrorReport timestamps (ErrorReport::fromThrowable() in marko/errors takes the timestamp as an argument)
• marko/log --- the log:clear age cutoff
• marko/log-file --- record times and the daily file name
• marko/testing --- TestClient’s REQUEST_TIME and cookie expiry (falls back to SystemClock when no clock is bound)

marko/admin-auth event timestamps come from the marko/database repository’s current instant rather than a clock of its own.

• marko/webhook --- signature timestamps, the freshness window, and attempt times
• marko/cache-array and marko/cache-file --- cache entry expiry and created_at
• marko/cache-redis --- the reported expiresAt() of a cache item (Redis itself enforces the TTL)
• marko/ratelimiter --- Retry-After
• marko/page-cache-file --- cached page expiry
• marko/notification and marko/notification-database --- created_at and read_at timestamps
• marko/broadcasting-amphp --- subscriber token expiry, event id timestamps, and replay buffer eviction
• marko/broadcasting-mercure --- subscriber JWT and cookie expiry
• marko/broadcasting-pusher --- request signature timestamps
• marko/media --- the YYYY/MM upload path
• marko/sse --- stream heartbeats and timeouts (SseStream defaults to SystemClock when you construct it without one)
• marko/database --- #[Timestamps] values and generated migration file names
• marko/queue --- the worker’s failed-job time
• marko/queue-database --- job availability, delays, reservation expiry and failed-job time
• marko/scheduler --- which tasks are due, the schedule:work loop, and overlap-mutex expiry

API Reference

SystemClock

use Marko\Clock\SystemClock;

public function __construct(DateTimeZone|string|null $timezone = null);
public function now(): DateTimeImmutable;

ClockInterface

use Psr\Clock\ClockInterface;

public function now(): DateTimeImmutable;

Related Packages

• marko/testing --- FakeClock for deterministic tests