PSR Clock

PSR Clock (psr/clock) is the official PHP-FIG package that holds the PSR-20 ClockInterface — a tiny, standardized contract for reading the current time. It defines a single method, now(), that returns a DateTimeImmutable, giving libraries and applications a shared abstraction over ‘what time is it right now’ instead of calling the global clock directly.

The package contains no clock implementation of its own; it is purely the interface. By type-hinting against ClockInterface and injecting a concrete clock, code becomes deterministic and testable — you can swap in a frozen or fake clock during tests — and interoperable across any framework or library that adopts the standard.

What You Get

• The PSR-20 ClockInterface with a single now() method
• A DateTimeImmutable return type for safe, immutable time values
• A shared abstraction any framework or library can adopt
• A dependency-free package with no runtime requirements beyond PHP
• A foundation for injecting frozen or fake clocks in tests

Common Use Cases

• Type-hinting services against ClockInterface instead of calling time() directly
• Injecting a fake or frozen clock to make time-dependent tests deterministic
• Standardizing time access across libraries that interoperate
• Decoupling business logic from the system clock for testability

Under The Hood

Architecture - The entire package is a single file, src/ClockInterface.php, declaring one method: now(): DateTimeImmutable. There is no implementation, no state, and no branching logic — the value is entirely in the shared contract it establishes. Consumers depend on the interface and receive a concrete clock through dependency injection.

Tech Stack - Pure PHP (^7.0 || ^8.0) with no runtime dependencies. Autoloading follows PSR-4 under the Psr\Clock namespace.

Code Quality - As a finalized PHP-FIG standard, the code is intentionally frozen and minimal; correctness is defined by the PSR-20 specification and its meta document rather than tests. The DateTimeImmutable return type enforces immutability at the type level, which is the key design guarantee.

API Design - The API could not be simpler: one method returning an immutable date-time. This minimalism is the point — it is trivial to implement, trivial to mock, and imposes no opinions on how time is sourced, which is why it has become a de facto foundation (nearly 15M monthly installs) for testable, interoperable time handling in PHP.