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 <[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
