Time\Instant and Time\Clock proposal

Under discussion. The RFC (version 1.0, dated 2026-09-21) proposes three symbols in the Time\ namespace: an immutable Time\Instant class for an absolute point on the timeline, a Time\Clock interface, and a Time\Clock\SystemClock implementation. Its proposed version is the next minor, PHP 8.7. The page's status line reads "Under Discussion" (it read "Unter Discussion" when first checked on 2026-10-01); the official RFC index lists it as discussion.

Design points stated in the RFC

• An instant carries no timezone or calendar; arithmetic moves it by a Time\Duration.
• Leap seconds are ignored, following common language and operating-system practice.
• A clock interface lets code obtain "now" through an injectable dependency, which helps testing.
• A toInstant() method on DateTimeInterface, DateTime and DateTimeImmutable would convert an existing object, dropping its timezone but keeping microsecond precision. A 2026-10-06 edit added this method to the backward-compatibility section: it could conflict with a method of the same name declared in a userland subclass. The RFC notes that adding symbols is generally not considered a break under policy.
• Time\Clock\SystemClock is a singleton. Its constructor is private, and the instance comes from SystemClock::get(). The authors made this change after list feedback (message 132825, 7 October). now() returns values that are not guaranteed to increase monotonically.
• Unix-timestamp conversions use a to prefix: toUnixTimestamp() and toUnixTimestampMilliseconds(). This follows the convention of toIso8601DateTimeString() and toInstant() (message 132829). getNanoseconds() keeps its name and returns the sub-second fraction (0 to 999 999 999). The RFC leaves the instant's epoch unspecified.
• Time\Instant will not implement JsonSerializable. In message 132827 the authors said JSON has no canonical representation for an instant, and that a method that always throws would make it look supported. They said json_encode()'s default object output is a problem for ext/json to solve. Regular PHP serialization is supported, but its format is an implementation detail.
• The authors want a configurable-resolution "coarse" clock to be a decorator, not part of SystemClock, and consider it out of scope, like testing clocks.
• The RFC compares Time\Clock with PSR-20's ClockInterface, which returns DateTimeImmutable instead; ready-made testing clocks are listed as future scope.

It builds on the Duration class RFC, which the official index lists as implemented. The vote, when opened, is a single 2/3-majority question.

Limitations

This page summarises the proposal only. The page still shows version 1.0 and has no changelog entry for these edits. The renames and the singleton come from the RFC stubs as checked at 16:01 UTC on 2026-10-07 and from the authors' messages. Other points in the review thread are still open. On 9 October the reviewer (Marc, who collected the review points on 6 October) replied: they accept keeping the coarse clock out of scope, but would prefer a future built-in coarse system clock over a decorator, because a decorator must read the precise clock first; they cited their own Linux arm64 measurements of about 13.3 ns for CLOCK_REALTIME and 3.3 ns for CLOCK_REALTIME_COARSE. They still object to the name getNanoseconds() and propose getNanoOfSecond() or getNanosecond() (matching DateTime::getMicrosecond()). These are review comments, not RFC changes. The page's last-modified line was cut off by the bounded fetch on 9 October, so a later page edit was not ruled out. On 9 October Tim Düsterhus agreed to disagree with a participant who wanted a clock implementing both Time\Clock and PSR-20's ClockInterface, and said a short note on this had been added to the rejected features. The wiki change feed summary for the 12:32 UTC edit instead reads "Add renaming now() to rejected features". The bounded fetch cut the page off before that section, so neither note was read on the page. Names, methods and the target version can change before a vote, and nothing here is available in released PHP.