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
