Re: [RFC] Time\Instant and Time\Clock
| From: | Tim Düsterhus | Date: | Tue, 22 Sep 2026 16:20:49 +0000 |
| Subject: | Re: [RFC] Time\Instant and Time\Clock | ||
| References: | 1 2 | Groups: | php.internals |
| Request: | Send a blank email to internals+get-132594@lists.php.net to get a copy of this message | ||
Hi
Replying with my personal opinion, not as the RFC author (since I didn't discuss this reply with Derick).
On 2026-09-22 17:14, Seifeddine Gmati wrote:
Could we name the proposed classThe proposed naming is consistent with JavaScript’s Temporal (https://developer.mozilla.org/de/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant) and Java’s java.time (https://docs.oracle.com/javase/8/docs/api/java/time/Instant.html), which are the primary sources of reference we used. I also believe that “real world time” and instead of “monotonic” time will be the primary use case and would thus prefer the simpler (and more widely used) name for that.Time\SystemTimeand reserveTime\Instantfor 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 theI agree that naming should be taken into account as part of this RFC, similarly how we already decided on Duration::divideInto(), despite not yet shipping it.
I would also like to see a staticFor the monotonic timer having a single static constructor definitely makes sense to me, because the use cases are much different and you can't meaningfully mock it anyway. For the real world clock, I think I would want to nudge users towards “doing the right thing” and use an injectable factory and therefore now provide the static factory, but I don't have particularly strong opinions regarding that. I don't think it should be a static method on theSystemTime::now()factory, and eventuallyInstant::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:$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?
Instant class, though, because that would intimately tie it to the SystemClock, which feels wrong. The correct approach would probably be a Time\now(): Instant function.
(Note: Please keep the RFC terminology in discussion of topics that are not about changing the terminology, seeing SystemTime in your example was very confusing since the RFC also has SystemClock.)
Also, If we are addingSimilarly, I can see that being a first class citizen for the monotonic timer (since the prime use case is measuring elapsed time), but not so much for the real world clock, where measuring elapsed time is just one operation of many.nowstatic 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 doingInstantOrSystemTime::now()->durationSince($this)).
Finally, I would reconsider includingI 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. Best regards Tim DüsterhusFrozenClockandOffsetClock. The RFC notes that specialised clocks can have different behaviours, but these two seem useful and sufficiently well-defined: -FrozenClocktakes a time value and always returns that value. ( potentionally withadvance(Duration $duration): voidandtravelTo(SystemTime $moment): void) -OffsetClocktakes another clock and a duration, and returns the wrapped clock’s current time plus that duration.