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

On Tue, 22 Sept 2026 at 15:21, Tim Düsterhus <tim@bastelstu.be> wrote: > > Hi > > following Time\Duration in PHP 8.6, Derick and I created an RFC for > Time\Instant and Time\Clock as the next part of the new date and time > API: > > https://wiki.php.net/rfc/time_instant_class > > This time we have several months until the next feature freeze, so > there’s place to discuss additional functionality that we missed. > Nevertheless we would like to keep the RFC focused so that every > decision gets the attention it deserves and some bits are already listed > as “Future Scope” to that effect. > > Best regards > Tim Düsterhus Hi Tim, Thanks for putting this together. I have a few suggestions about naming, obtaining the current time, and the clock implementations. Could we name the proposed class Time\SystemTime and reserve Time\Instant for a future high-resolution monotonic clock API? Rust uses this distinction, and I find it helpful: [SystemTime](https://doc.rust-lang.org/std/time/struct.SystemTime.html) represents wall-clock time, which can change following clock corrections, while [Instant](https://doc.rust-lang.org/std/time/struct.Instant.html) represents monotonic time, suitable for measuring elapsed time, benchmarking, etc. I appreciate that monotonic time is explicitly left to future scope. I’m suggesting we settle the naming with both concepts in mind now, without necessarily introducing both in this RFC. This is also the distinction I use in Whim's [Instant](https://github.com/carthage-software/whim/blob/main/lib/src/Time/Instant.whim) and [SystemTime](https://github.com/carthage-software/whim/blob/main/lib/src/Time/SystemTime.whim) types for reference. I would also like to see a static SystemTime::now() factory, and eventually Instant::now() for monotonic time. I understand the rationale for an injectable clock, but I think the two approaches can coexist. When I simply need the current time, I would prefer: ```php $time = SystemTime::now(); ``` Having to instantiate a clock, or pass one through several layers of an existing application for an occasional time read, feels unnecessarily cumbersome. People who need control over time can use an injected clock; callers using the static factory would knowingly give up that control. Is there a reason to exclude the convenience API? Also, If we are adding now static method, I think adding [elapsed()](https://doc.rust-lang.org/src/std/time.rs.html#660-662) would also be helpful. ( a shorter way of doing InstantOrSystemTime::now()->durationSince($this) ). Finally, I would reconsider including FrozenClock and OffsetClock. The RFC notes that specialised clocks can have different behaviours, but these two seem useful and sufficiently well-defined: - FrozenClock takes a time value and always returns that value. ( potentionally with advance(Duration $duration): void and travelTo(SystemTime $moment): void ) - OffsetClock takes another clock and a duration, and returns the wrapped clock’s current time plus that duration. More elaborate behaviour could remain in userland. For these basic implementations, though, I don’t see much ambiguity in either the API or the semantics. Including them would save users from repeatedly implementing the same small classes or adding a Packagist dependency for them, and would make the clock abstraction useful out of the box for testing. Best regards, Seifeddine