Following up on my previous message about the method names,I noticed one separate technical point.
The RFC specifies nanosecond precision for Time\Instant, but it is not clear whether toIso8601DateTimeString() preserves that precision in its output. Could the RFC clarify the fractional-second format and whether an optional precision argument is supported? I’m suggesting this only to clarify the existing method’s contract. Best regards, Théo > On 23 Sep 2026, at 19:29, Tim Düsterhus <[email protected]> wrote: > > Hi > > On 2026-09-23 17:02, Larry Garfield wrote: >> - Why is the representable range unspecified? Can we at least hint at what >> it is? If I cannot even guarantee that next week is within range, I >> basically cannot trust this API at all. (Later on in the prose the text >> says "the same as DateTimeImmutable", but I don't know what that is off >> hand. It should be specified more explicitly, and that later captured in >> documentation, even if it's just a minimum and subject to system details.) > > “and will be left to implementation constraints”. I plan to clarify that > further when the general API design is finalized and Derick and I are looking > into the implementation to figure out the details. The limits will be > “reasonable computational limits” - so you’ll be able to represent Instants > until at least the release of PHP 8.7 ;-) > > I added an item to the Open Issues to keep track of that. > >> - Why is a compare() method needed if Instant already supports <, >, etc? > > API consistency with Duration. Also a method has proper typing and works with > first class callables / PFA. Duration specifically had this example: > > usort($durations, Duration::compare(...)); > >> Also, the serialization format of other values has often been subject to >> discussion (eg, Enums), so why is it omitted here? > > The internal state of Instant is deliberately unspecified and that extends to > serialization. The serialization format will be portable across 32- and > 64-bit versions of PHP and backwards compatibility with existing serialized > data will be kept across PHP versions. I just clarified that part in the RFC > text. If you need to look at the output of serialization you are doing > something very wrong. I consider the enum discussion to be a different case, > since they introduced an entirely new type specifier `E`. Instant will just > be a plain old class that implements (the equivalent of) `__serialize()` and > `__unserialize()`. > >> - It's not clear to me how I would serialize an Instant outside of PHP, say >> to store it in a DB. UTC ISO8601? If so, that should be stated explicitly >> (and again, replicated to the docs eventually) to avoid confusion and people >> trying to invent clever mechanisms. > > As with any other value object, the best serialization format depends on your > exact use case. If an HTTP API provides you times as the number of > milliseconds since the Unix epoch, then you would use the > `fromUnixTimestampMilliseconds()` constructor to create an Instant from it. > If an API expects an ISO-8601 string as input, you would use the > `toIso8601DateTimeString()` getter. All the getters and constructors are > valid options for serialization and each constructor is paired with a getter. > Even just `serialize($instant)` can be a valid option. As already noted in > the RFC, the ISO-8601 format (and of course `serialize()`) is the portable > one that is capable of representing all possible Instants. > > For custom formats, in particular formats with an implied timezone, you’ll > need to wait for the future scope “Instant + Timezone” class. > >> My big issue, though, is context. This is very clearly part 2 of N, which >> is fine. Presumably you and Derick have a roadmap between you of what the >> end goal looks like and the moving parts that will be added, even if it's in >> steps. But that's not documented anywhere other than your heads, AFAIK, and >> the future scope section as currently written is barely 3 of N, and not in >> detail. >> I realize that designs change over time as they're implemented, which is >> totally fine, and all the details of later steps have likely not been worked >> out yet, which is also totally fine. But I still need to see the big >> picture, at least at a coarse resolution, to understand this RFC in context. >> Things that we feel are missing may be missing not out of incompleteness >> but "that's step N+3", which may be a perfectly good design but that's not >> at all apparent. >> I would strongly urge you to post (probably as an RFC page, even though it's >> not a full RFC) an overarching roadmap/plan for PHP Time TNG, so we can get >> a sense of where we're going. That will allow us to see each RFC in its >> appropriate context, and clearly note when things have been pushed to later >> that "later" is defined and documented. (Eg, the FrozenClock idea.) > > Each part of the series is intended to stand on its own and to be complete > enough to be usable for production use cases rather than just toy examples. > The end goal is to model (all) real-world concepts of time and the focus of > each RFC text is explaining that concept and how it was modeled. If you > expected the modeling to cover something and the RFC doesn’t mention it (“I > expected it to do X, why doesn’t it?”), we failed at that explanation and I > recommend raising the issue on the mailing list. > > The evolution of the new date and time API is also not linear, but rather a > graph connecting the various concepts that can be worked on in any order, as > long as the dependencies are satisfied. To get a rough idea of where we’re > heading you can take a look at java.time and JavaScript’s Temporal. > > Best regards > Tim Düsterhus
