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 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.
The 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.
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
I 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 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?
For 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
the `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 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)` ).
Similarly, 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.
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.
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.
Best regards
Tim Düsterhus
