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

On Tue, Sep 22, 2026, at 9:20 AM, Tim Düsterhus wrote: > Hi > > following Time\Duration in PHP 8.6, Derick and I created an RFC for > Time\Instant and Time\Clock as the next part of the new date and time > API: > > https://wiki.php.net/rfc/time_instant_class > > This time we have several months until the next feature freeze, so > there’s place to discuss additional functionality that we missed. > Nevertheless we would like to keep the RFC focused so that every > decision gets the attention it deserves and some bits are already listed > as “Future Scope” to that effect. > > Best regards > Tim Düsterhus I am broadly in favor of this proposal, though I have some questions/concerns. (In reading order...) - 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.) - Why is a compare() method needed if Instant already supports <, >, etc? - "Serialization of Time\Instant will be supported, the exact format is considered an implementation detail. " - Should be a period, not a comma.. Also, the serialization format of other values has often been subject to discussion (eg, Enums), so why is it omitted here? - I am fine with this being essentially a port of PSR-20, and the naming doesn't bother me. - I also agree that not having Instant:now() is the correct approach. If someone really wants to just pluck the current time out of thin air, testing be damned, that's easy enough: $now = new SystemClock()->now(); Moreover, making it injectable is also quite trivial thanks to modern syntax: class SomeService { public function __construct( private SomeDependency $dep, private Clock $clock = new SystemClock(), ) {} public function doThings() { $now = $this->clock->now(); // The system time, unless it's been overridden by injection. // ... } } That's a perfectly fine approach in my mind, and offers all the pieces of flexibility that we need in that regard. That said, I am also on-board with having the trivial/obvious test clocks provided in core, be they in this RFC or a follow-up. In short, yes please deprecate PSR-20. :-) - 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. 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.) --Larry Garfield