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

Hi Tim, Thank you for considering the ISO 8601 date-time representation in the new API ! If I may add one small suggestion: could toIso8601DateTimeString() be shortened to toIso8601String() and fromIso8601DateTimeString() to fromIso8601String() ? Since Time\Instant already represents a date-time value, these shorter names remain clear and are easier to use. Best regards, Théo > On 23 Sep 2026, at 19:29, Tim Düsterhus <tim@bastelstu.be> 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