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
