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:
```php
$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
