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

Hi On 2026-10-05 17:29, Rob Landers wrote:

I'm just now getting around to reading over the RFC, and I've read most messages but not all of them. So, I apologize if I'm reopening any old discussions here.

The only duplication was the JSON serialization that had also been mentioned by Ilia (who I'm Ccing here).

After spending much of the last 4-5 years working on a database that needs to deal with relativity, I'd recommend dropping the physics framing in the introduction. Time doesn't move at the same speed for everyone, even on Earth, and you don't specify a frame of reference for the instant. It would also make it easier to explain until as "computes the difference between two represented time values. It does not establish how much physical time elapsed between the events that produced those values."

Thanks for the physics discussion in Discord. To loop in the list: Rob is correct here, I'll check what I can do to satisfy the physics experts without leading other folks down the “I need a timezone” track.

This also raises a question about uncertainty. I appreciate that the RFC distinguishes the nanosecond precision of the representation from the resolution of the underlying clock. However, Clock::now() returns only an Instant, with no way through that contract to convey the source resolution or any available uncertainty information. I've had servers lose access to their hardware clock due to hardware malfunctions, so this is not just a theoretical concern. Where that information is available, it should be preserved alongside the reading. Where it is unknown, it should remain explicitly unknown. Printing nine fractional digits cannot supply that information.

Uncertainty is likely not of interest to the average user or something they understand: They just trust that their operating system provides them with the correct time. For applications where this matters adding a custom extension with a “ClockWithUncertainty” clock that returns the Instant + a Duration would be the right choice. The current design is in line with what virtually all the other programming languages do for their standard library. Marc also suggested exposing clock_getres() on the SystemClock, I'll reply there. In any case, I don't think this is something that belongs on the Clock interface, since it increases the API complexity for little benefit.

I think there are some things worth addressing in the current RFC: 1. Instant should throw when serialized to JSON. I understand the argument is that applications should choose their own representation, but the choice should be enforced rather than silently doing the wrong thing. Or provide an opaque serialization that can restore the Instant.

I discussed this with Derick and it's our position that: 1. As you mentioned and as I said in https://news-web.php.net/php.internals/132764 that there is no single canonical representation for JSON and that users need to make a choice themselves. 2. That implementing JsonSerializable just to always throw an exception would be misleading, because from the API surface it very much looks like JSON serialization would be supported. That json_encode() includes a useless default serialization for arbitrary objects instead of requiring an opt-in is something that should be fixed in ext/json and not worked around for every (value) object we implement. Since there is no “json decode to object”, an opaque serialization that can restore the Instant is not really a thing. If users need to manually call methods, they can just go via ISO-8601.

2. DateTimeInterface is missing the toInstant() method, is that by design?

No. I just forgot that the interface exists. Now added.

3. The backward-compatibility section still says this RFC only introduces three new namespaced symbols. It should also cover the new methods on DateTime and DateTimeImmutable, including potential conflicts with existing subclass methods named toInstant().

Did some preliminary adjustments there. Might tune the phrasing later. Best regards Tim Düsterhus