Re: [RFC] Time\Instant and Time\Clock

Hi On 2026-09-22 18:51, Seifeddine Gmati wrote:

I agree that wall-clock time will be used more often, but I’m not convinced that Instant is necessarily simpler or clearer than SystemTime. Arguably, the latter communicates more directly that the value comes from the system clock and is subject to clock adjustments. That said, let’s see what Derick and others think about the naming.

Yes, Instant is clearer than SystemTime, because of the Time suffix that implies “time as shown on a clock”, which is *not* what the proposed Instant represents: Namely a point on the timeline of the universe. Other names that I've seen used for this concept are “Timestamp” or “Moment”, with “Instant” being the most widely used in the references we looked at. Specifically, as part of future scope we're also planning for “Date” and “Time” classes that represent a calendar date (year, month, day) and a “clock time” (hour, minute, second, fractional second) respectively. Java calls these LocalDate and LocalTime. Calling the “point in time” class “SystemTime” would invite confusion with whatever the “clock time” object would be.

A Time\now() function would address the convenience issue, although I still think discoverability is better when the operation is available directly on the relevant type. But I don't have a strong opinion here.

Java has an overloaded Instant.now() and Instant.now(Clock) where the parameter-less version defaults to the system clock. That would theoretically work for PHP, but I feel that a free-standing function matches PHP’s existing API design and capabilities better (Java doesn't have bare functions, unless that changed since I last looked at it).

I also see some value in elapsed() for wall-clock instants, even though I agree that it is more useful and reliable with a monotonic clock. For example, I might use something like this for quick debugging or logging:

$startedAt = Instant::now();

$result = evaluate_expression($expr);

fwrite(STDERR, 'Took ' . $startedAt->elapsed());

For this kind of informal measurement, I may not need the stronger guarantees of a monotonic clock. The operation would, of course, remain subject to wall-clock adjustments. Rust returns an error if the clock moves backwards; PHP could throw an exception in that case. I’m not strongly attached to including this method for wall-clock time, but I do think it has plausible uses.

The monotonic clock would not be much more complicated. Using the hypothetical name “Stopwatch”, it could be:

    $watch = Stopwatch::start();
    // …
    echo "Took ", $watch->elapsed();

In fact using Stopwatch as the name might allow for a nice API where a method could store “named round timers” as an array. Something like:

    $start = Stopwatch::start();
    prepare();
    $start->snapshot('preparation');
    execute();
    $start->snapshot('execution');
    var_dump($start->snapshots);

Where the 'execution' snapshot would be measured starting from the 'preparation' snapshot. Or even:

    $duration = Stopwatch::measure(execute(...));

to measure a single function call.

I would be open to doing those two as an (immediate) follow-up, since I feel they have plenty of bike-shedding potential on their own. So they would also land in PHP 8.7, but not distract from the main API design.

I’m fine with leaving FrozenClock and OffsetClock to an immediate follow-up RFC. My only concern is the current wording that test clocks are better left to userland because their behaviour varies widely. That argument could later be used against adding even these well-defined clocks to the standard library. Perhaps they could instead be mentioned explicitly under “Future Scope,” without committing this RFC to their exact APIs.

Fair enough. I'll put rephrasing that paragraph on my list to discuss with Derick for the next RFC update. Best regards Tim Düsterhus