Hi

Later on though you are mentioning that "Following the lead of
virtually all programming languages and operating systems, leap seconds
are ignored."

Is that only with relation to the Iso8601 strings? Or is that a general
shortcoming?

Leap seconds are treated as non-existent as an integral part of the
class design. Operating systems, in particular Unix-based systems as the
arguably most common runtime environment of PHP, don't expose leap
seconds in their time retrieval APIs and pretend very hard that leap
seconds don't exist, either by “halting the clock” for 1 second, by
repeating the second, or by smearing the leap second over a larger
time-frame of “slightly more than a second”-seconds (e.g. across the
preceding 1000 seconds as proposed by UTC-SLS).

Trying to support leap seconds in PHP when the operating system does not
would mean that PHP would need to keep its own list of when a leap
second should have occurred and would require users to actually update
PHP to get correct information (which is something that most certainly
won't happen).

It would necessarily also mean that the difference between two Instant’s
->getUnixTimestamp() values would differ from the duration returned by
until() and that two Instants with the same Unix timestamps might
compare unequal.

Given that virtually everyone ignores leap seconds and given that there
hasn't been one for the past 10 years and there are plans to abolish
them by 2035, I don't think it is useful to make PHP in any way special.
This would just invite bug reports from confused users.

So no shortcoming, intentional and deliberate design decision. The
“unique point on the timeline” phrasing is to establish a reasonable
mental model of why Instants don’t have a timezone and why this is a
useful concept, not as a 100% accurate representation of physics.

The other point I find irritating is the naming of the Clock
interface. While I can understand the reasoning behind it I see
irritation in the community upcoming as the CLockInterface now
suddenly returns 2 different things, depending on which ClockInterface
people are talking about.

While it doesn't seem to be written down as policy - but I could swear
this topic came up on Internals at least - PHP doesn't use the
Interface suffix to indicate interfaces in newly designed APIs.
Following the precedent established by ext/random in PHP 8.2 with
Random\Engine, the interface is the bare name and the concrete
implementations sit in a sub-namespace named after the interface.

Thus there is a clear difference in naming even for the unqualified
interface name.

Is there a way to Unify the ideas behind Time\Clock and
Psr\Clock\CLockInterface?

The proposed new date/time API is a greenfield design to fix issues with
the existing API. We deliberately don't want to “infect” the new API
with ideas from the legacy API and returning an object carrying a
timezone from a clock, as done in PSR-20, is the wrong design. now()
is the obvious name for the method and that's why the RFC indicates that
an adapter is required to satisfy both interfaces from the same source
of truth during the migration phase.

As right now the Time\Clock is not a direct replacement of
Psr\Clock\ClockInterface as - at the current time - there is no way to
generate a DateTimeImmutable directly from a Time\Instant.

Yesn't: You can bridge the gap by using
DateTimeImmutable::createFromTimestamp($instant->getUnixTimestamp())->setMicrosecond(intdiv($instant->getNanoseconds(),
1000)).

That said, I acknowledge that it's not particularly pretty and we
discussed adding another fromInstant() constructor and ->toInstant()
getter to DateTimeImmutable. The compatibility layer would be sitting on
the old API to keep the new API clean.

Best regards
Tim Düsterhus

Hi

Replying with my personal opinion, not as the RFC author (since I didn't
discuss this reply with Derick).

Could we name the proposed class Time\SystemTime and reserve
Time\Instant for a future high-resolution monotonic clock API? Rust
uses this distinction, and I find it helpful:
SystemTime
represents wall-clock time, which can change following clock
corrections, while
Instant
represents monotonic time, suitable for measuring elapsed time,
benchmarking, etc.

The proposed naming is consistent with JavaScript’s Temporal
(https://developer.mozilla.org/de/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant)
and Java’s java.time
(https://docs.oracle.com/javase/8/docs/api/java/time/Instant.html),
which are the primary sources of reference we used.

I also believe that “real world time” and instead of “monotonic” time
will be the primary use case and would thus prefer the simpler (and more
widely used) name for that.

I appreciate that monotonic time is explicitly left to future scope.
I’m suggesting we settle the naming with both concepts in mind now,
without necessarily introducing both in this RFC. This is also the

I agree that naming should be taken into account as part of this RFC,
similarly how we already decided on Duration::divideInto(), despite not
yet shipping it.

I would also like to see a static SystemTime::now() factory, and
eventually Instant::now() for monotonic time. I understand the
rationale for an injectable clock, but I think the two approaches can
coexist. When I simply need the current time, I would prefer:

$time = SystemTime::now();

Having to instantiate a clock, or pass one through several layers of
an existing application for an occasional time read, feels
unnecessarily cumbersome. People who need control over time can use an
injected clock; callers using the static factory would knowingly give
up that control. Is there a reason to exclude the convenience API?

For the monotonic timer having a single static constructor definitely
makes sense to me, because the use cases are much different and you
can't meaningfully mock it anyway.

For the real world clock, I think I would want to nudge users towards
“doing the right thing” and use an injectable factory and therefore now
provide the static factory, but I don't have particularly strong
opinions regarding that. I don't think it should be a static method on
the Instant class, though, because that would intimately tie it to the
SystemClock, which feels wrong. The correct approach would probably be
a Time\now(): Instant function.

(Note: Please keep the RFC terminology in discussion of topics that are
not about changing the terminology, seeing SystemTime in your example
was very confusing since the RFC also has SystemClock.)

Also, If we are adding now static method, I think adding
elapsed()
would also be helpful. ( a shorter way of doing
InstantOrSystemTime::now()->durationSince($this) ).

Similarly, I can see that being a first class citizen for the monotonic
timer (since the prime use case is measuring elapsed time), but not so
much for the real world clock, where measuring elapsed time is just one
operation of many.

Finally, I would reconsider including FrozenClock and OffsetClock.
The RFC notes that specialised clocks can have different behaviours,
but these two seem useful and sufficiently well-defined:

• FrozenClock takes a time value and always returns that value. (
  potentionally with advance(Duration $duration): void and
  travelTo(SystemTime $moment): void )
• OffsetClock takes another clock and a duration, and returns the
  wrapped clock’s current time plus that duration.

I would be open to doing those two as an (immediate) follow-up, since I
feel they have plenty of bike-shedding potential on their own. So they
would also land in PHP 8.7, but not distract from the main API design.

Best regards
Tim Düsterhus

Hi

• 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

Hi

• The behavior of Instant::toIso8601DateTimeString() regarding
  fractional seconds was adjusted again: Trailing zeros will now be kept
  to make the precision supported by Time\Instant explicit.
  2026-09-29T16:42:45.5Z could mean “exactly 0.5 seconds” or “0.5
  seconds ± 0.05 seconds” whereas 2026-09-29T16:42:45.500000000Z is
  explicit as to how precise the data is. This might matter for consumers
  that also store an “uncertainty” range.

Forgot to mention, but it's in the RFC: The fractional part will be
entirely omitted if it's zero. While that drops the explicit precision
information in that case, it should also improve interoperability with
consumers who are not prepared to handle fractional seconds. A consumer
that already supports fractional seconds should be able to deal with
trailing zeros just fine.

Best regards
Tim Düsterhus

=========
Comment 2

The RFC states:

An Time\Instant carries no timezone. It represents a unique point
on the timeline of the universe.

Why is there no explicit or implicit timezone attached? The RFC reads
to me like there is an implicit timezone attached, namely the UTC
timezone. Especially the toIso8601DateTimeString() function which
always returns the 'Z' timezone identifier seems to imply an implicit
UTC timezone?

I think I can answer that one. It's because for display purposes some
consistent way of labelling Instants is required so that they can be
displayed. Using an ISO8601 string just makes that label human-readable;
the UTC timezone is not an intrinsic property of the Instant but of the
labelling (nor are the labels themselves, for that matter). Instants
would still be a thing and people would be able to say that two events
occurred "at the same time" even if the International Meridian
Conference had never happened.

(I mentioned earlier during the Duration discussion that time arithmetic
is a one-dimensional real affine space. Such a space can be formalised
as a set of points and a space of free vectors (and a way to add points
and vectors together). Here, Durations provide the vectors and Instants
provide the points.)

I think precision should somehow be an explicit part of \Time\Instant
class. How precise is the \Time\Instant?

Well, then it's not an instant, is it? It's a combination of an
instant ("now") and a duration ("and the subsequent sixty seconds").

Hi

=========
Prologue

Well, I do have 8 comments on the Request For Comments (RFC).
This is a lengthy post, be prepared for a long reading time.

Thank you! I'm fully prepared for lengthy emails and am happy to answer
any clarifying questions to make sure we're all on the same page with
regard to what is being proposed. Your email is also nicely structured,
which makes it easy to work through it.

=========
Comment 1

Is \Time\Instant meant to be immutable? If so, please state that in
the RFC.

Yes. This was already implied since the stub specifies that it's a
readonly class, but I've just adjusted the RFC text to explicitly
include the word “immutable”.

=========
Comment 2

The RFC states:

An Time\Instant carries no timezone. It represents a unique point
on the timeline of the universe.

Why is there no explicit or implicit timezone attached? The RFC reads
to me like there is an implicit timezone attached, namely the UTC
timezone. Especially the toIso8601DateTimeString() function which
always returns the 'Z' timezone identifier seems to imply an implicit
UTC timezone?

Timezones are a concept to translate a point in time (“Instant”) into
date and time as shown on a clock. Both 2026-09-30T20:13:30+02:00 and
2026-09-30T18:13:30+00:00 refer to the same point in time. The point in
time itself does not have a timezone. The ISO-8601 getter chooses to
represent the point in time with the UTC / Zulu timezone, because
specifying an offset is required for the “date and time” representation
to be unambiguous. It would be equally valid for it to select a random
offset each time you use it. Using UTC / a zero offset is just a
pragmatic choice for best interoperability.

=========
Comment 3

Why is it called \Time\Instant? I find \Time\UtcInstant a better name,
which embeds the timeline unit used.

\Time\UtcInstant leaves room for future different timeline Instants
like:

• \Time\TaiInstant (International Atomic Time)
• \Time\Ut1Instant (Universal Time)
• \Time\TtInstant (Terrestrial Time)

UTC, TAI and the others are just different projections of a “point on
the timeline of the universe” and the Instant class is largely
agnostic to them. It differs from a perfect model of the timeline of the
universe in that leap seconds are ignored (see my reply to Andreas
https://news-web.php.net/php.internals/132600), since that is what the
computing industry converged on. Nevertheless, this brings us back to
comment (2): The differences between UTC, TAI and the others concern the
clock time. The point on the timeline of the universe remains the
same.

And of course Time\Instant is just the ergonomic name, matching the
precedent set in Java (java.time.Instant) and JavaScript
(Temporal.Instant).

=========
Comment 4

The \Time\Clock interface conflicts with PSR-20 Clock interface, see
https://www.php-fig.org/psr/psr-20/ . A class can never implement both
interfaces at the same time. This will hinder adoption.

The RFC acknowledges that. Writing an adapter is easy, particularly
since the addition of the DateTimeImmutable::toInstant() method to the
proposal.

Consider renaming the function now(): \Time\Instant function to
function nowAsInstant(): \Time\Instant.

now() is the obvious name for the method. Using something else would
mean that the proposed API would still suffer from a decision made for
compatibility after everyone has migrated to it and PSR-20 is long
forgotten. The horizon we are planning with is at least the next 15
years, but we're hoping that the API holds up for even longer.

For the same reason the compatibility layer with DateTimeImmutable is
explicitly added to the old API so that it is possible to deprecate
and remove the old API without affecting the new one.

=========
Comment 5

The RFC introduces a SystemClock class:

<?php

final readonly class SystemClock implements \Time\Clock
{
    public function __construct() {}

    /**
     * The current instant, at the resolution offered by the platform
     * clock,
     * which is generally coarser than nanoseconds.
     *
     * Returned values are not guaranteed to be monotonically
     * increasing across calls.
     */
    public function `now()`: \Time\Instant {}
}

?>

Why is SystemClock not a Singleton? Can there be multiple different
system clocks in practice? I believe a System Clock, with the emphasis
on "System" is a System Wide clock. This clock is not bound to PHP,
but to all processes running on the system, including Apache,
shell-scripts, NGINX and others.

Conceptually there is only one SystemClock and internally each
SystemClock object accesses the same clock source provided by the
operating system. But you are making a good point here: Replacing the
constructor with a static ::get() method or similar would make that
explicit and would also allow for reducing memory usage when
SystemClock objects are obtained at different places in the code
(instead of being pulled from a dependency injection container). I'll
put this on my list to discuss with Derick (and am happy to receive
naming suggestions for such a static getter).

The RFC also states a FrozenClock for testing purposes. Well this

The FrozenClock is not part of the RFC. It is provided in the
non-normative part of the RFC as an example to showcase how the Clock
interface can be useful for testing purposes. Whether or not a
FrozenClock will be added to PHP itself is to be decided as part of a
future RFC (by different authors, as indicated in my email from
yesterday).

pattern is not always going to work. Especially when an application
(the main program) uses Composer libraries and wants to freeze time
for each and everyone, including the vendor directory. Because not
every library in the vendor directory uses SystemClock. They all
use time(), because that is currently the standard way to obtain
the System Clock. Time freezing must involve the time() function!

It is debatable whether time() is the standard way to access the
system clock. It lacks support for fractional seconds and has terrible
ergonomics due to returning a bare integer. It is certainly still in
common use, but I'd argue the current best practice is a
DateTimeImmutable object, ideally one you obtained from a PSR-20
clock.

I think SystemClock should be removed from this RFC, it deserves
a seperate RFC. That RFC should also explore a frozen time()
function. Meaning the output of time() can be frozen recursively.
Because of this probably the \Time\Clock interface should also
be moved to that new RFC.

The point of the new date and time API is to completely supersede the
existing date and time API with a proper API design matching best
practices. Superseding the existing API includes the time() function -
which I would say is already a legacy API as of today, since
DateTimeImmutable does everything time() does and it does it better
(except maybe for brevity).

=========
Comment 6

Why does \Time\Instant not have a named constructor
public function fromSystemClock(): \Time\Instant ?

Why all the complexity of constructing a \Time\SystemClock and
calling now()? The System Clock is a Singleton and is always
available, as the time() function shows.

See https://news-web.php.net/php.internals/132594. “Injecting” a clock
would be the correct solution. If SystemClock was made a singleton
with a static getter as mentioned above (while still implementing the
interface), this would allow for:

 SystemClock::get()->now()

for simple use cases and one-off scripts, which would be even shorter
than your proposed:

 Instant::fromSystemClock()

=========
Comment 7

The RFC states:

PHP currently offers two ways to represent such a point, and both
are unsatisfying for the general case. A plain int as returned by
time() discards all sub-second precision and carries no type
information, leaving the question of “is this seconds, milliseconds
or something entirely different” to documentation instead of the
type system.

I want to bring something else to the table. What if one wants less
precision? What if one does not want seconds, milliseconds,
microseconds, nanoseconds? How is that going to fit into the
type system?

The Instant represents a point in time as precisely as possible. If
for some reason you need less precision, you can adjust it using the
->add() and ->sub() methods as desired. Please also see
https://news-web.php.net/php.internals/132621 for a possible future
scope ->truncateTo() method, but …

As a practical example, take a public transportation coach. The coach
has a schedule which is expressed in minutes, never in seconds. The
same argument, only minutes precision, goes for flight departures
and arrivals. Also ferries express their times in minutes.

… using an Instant to represent a public transportation schedule is the
wrong abstraction: Public transportation works on “date and time” as
shown on a calendar and a clock and only becomes meaningful once you
involve timezones. This is particularly important when a DST changeover
happens or your jurisdiction changes timezone rules: Now the point on
the timeline of the universe where your bus departs is different, but
the time shown on your wristwatch has remained the same.

=========
Comment 8

The RFC states:

Extensions may want to adjust their API to take Time\Instant
in addition to an int representing a Unix timestamp or an
object implementing DateTimeInterface.

With regard to the DateTimeInterface, I want to share that this
interface is an internal interface and can't be implemented by
user-space classes. See also issue #23543 at
https://github.com/php/php-src/issues/23543

To clarify, this does not work:

<?php

class MyTime implements DateTimeInterface
{
}

// Fatal error: DateTimeInterface can't be implemented by user classes
?>

That is an accurate observation, but not relevant to the quoted part. I
think there might be a misunderstanding: What the quote is saying is
that if there is a function foo(DateTimeInterface $when) it should be
adjusted to foo(DateTimeInterface|Instant $when) so that it is
possible to use it with the new API without needing to first convert the
Instant into a DateTimeImmutable.

Best regards
Tim Düsterhus

Hi

1. toIso8601DateTimeString() output width. Omitting the fraction only
   when it is zero makes the output format depend on the value. A consumer
   that can't parse fractions passes tests with whole-second fixtures,
   then
   fails on almost every SystemClock value in production, so the interop
   benefit doesn't hold. It also breaks string ordering:

You are correct that SystemClock will emit fractional seconds in
virtually all cases. However from my experience with dealing with API
responses, they rarely contain sub-second information and fractional
seconds are accordingly omitted from the ISO-8601 string. When using
those as inputs, the “lack of fractional seconds” roundtrips and any
math with Durations that are integral multiples of a second will keep
that property.

"2026-09-29T16:42:45Z" sorts after "2026-09-29T16:42:45.500000000Z",
and
people do store these in VARCHAR columns and ORDER BY them. Always
emitting 9 digits gives fixed width, chronological string order for
years 0000 to 9999, and the explicit precision you were after.

As you say yourself, the VARCHAR ordering breaks down for years before
0000 and after 9999 since a mandatory sign will be added. While these
are well outside our lifetimes, I don’t think “always emitting
fractional seconds allows for naive string-based ordering” follows from
that, since it still breaks down for points in time that are explicitly
supported by the Instant class.

For proper ordering the Instant::compare() method is provided and
users should use the date/time types provided by their database (e.g.
timestamptz for PostgreSQL), which will also allow for in-database
time arithmetic and default values (e.g. provided by NOW()).

2. The accepted grammar of fromIso8601DateTimeString(). "May not
   support
   all legal formats, extendable by a PR" means the accepted set gets
   decided in code review rather than by the vote. I'd like the RFC to
   guarantee RFC 3339 date-time (plus the expanded years the getter emits)

The RFC already specifies that:

It naturally will support all possible return values of
toIso8601DateTimeString().

And in practice the toIso8601DateTimeString() getter implements the
RFC 3339 subset of ISO-8601. That would leave non-Z offsets, which are
easy enough to include (and already supported by DateTimeImmutable, so
we can just borrow from there).

and state the outcome for: more than 9 fractional digits, comma decimal
sign, lowercase t/z, space separator, -00:00, 24:00:00 and 23:59:60. On
the last one, java.time parses 23:59:60 as 23:59:59 rather than
rejecting it, and RFC 3339 explicitly permits :60. Rejecting is
defensible, but it should be written down.

The RFC notes that the parser is strict: All invalid inputs will be
rejected (that includes the space separator). Other than that the inputs
that can be parsed losslessly fall under the “extendable by PR” rule. As
an example, if a comma decimal is not supported in the initial version,
it can be added later without introducing a breaking change. The input
is well-defined and representable by Instant. The same applies to
lowercase t/z or the “basic format” 20261001T194330+0200.

The behavior for lossy inputs I’ll put on my list to discuss with
Derick.

3. json_encode(). With no public properties, json_encode($instant)
   yields {}. Duration and DateTimeImmutable both encode to something
   meaningful today, so a silent {} is a trap for any API response
   carrying
   a timestamp. Either implement JsonSerializable returning the ISO-8601
   string, or state that {} is intentional.

I’ll put that on my Derick list, but my personal answer is: As the RFC
notes there is no single representation that is correct in 100% of the
cases. Some JSON payloads might want an ISO-8601 string, some might want
a Unix timestamp with millisecond precision. Not implementing
JsonSerializable forces the user to make a choice - it is unfortunate
that PHP’s JSON serializer defaults to a useless object representation
rather than requiring an opt-in. For the same reason there is no
__toString(), but a toIso8601DateTimeString() (see also the design
of ext/uri).

On the exceptions open issue: splitting TimeException into subclasses
later is BC-safe, since catch (TimeException) keeps working, so I don't
think it needs to block this RFC.

Yes. However we’ve already deferred adding the hierarchy in the Duration
RFC, so I put it on the list for discussion. But it probably makes sense
to define the remaining classes before committing to the final
hierarchy.

Best regards
Tim Düsterhus

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

Why would this not become an always bundled ext/time?

For the “always enabled” extensions it doesn't really matter where the
code is located and the (observable) end result for the user is the same
(except for ReflectionExtension). Time\Duration went into ext/date for
simplicity, since timelib is already properly wired into ext/date.

Since this proposed new date/time API will be the successor of the old
date/time API, why not also physically & cleanly separate the new from
the old stuff? ext/standard is such a kitchen sink already that I
wonder why modern successors would not live in a more "sensible"
structure. Imagine a (far) future where we could chose to compile PHP
with or without legacy stuff -- clean separation would make this
easier.

It's ext/date, not ext/standard where the API lives. For Time\Duration
we already split off the implementation into a separate and effectively
standalone php_time.h header with php_time.c and time_duration.c
source files, instead of the php_date.[ch] kitchen sink.

As far as my understanding of the policy goes, nothing would forbid
making this an extension (see ext/uri)?

That is accurate.

Best regards
Tim Düsterhus

Hi

I'm just now getting around to reading over the RFC, and I've read most
messages but not all of them. So, I apologize if I'm reopening any old
discussions here.

The only duplication was the JSON serialization that had also been
mentioned by Ilia (who I'm Ccing here).

After spending much of the last 4-5 years working on a database that
needs to deal with relativity, I'd recommend dropping the physics
framing in the introduction. Time doesn't move at the same speed for
everyone, even on Earth, and you don't specify a frame of reference for
the instant. It would also make it easier to explain until as
"computes the difference between two represented time values. It does
not establish how much physical time elapsed between the events that
produced those values."

Thanks for the physics discussion in Discord. To loop in the list: Rob
is correct here, I'll check what I can do to satisfy the physics experts
without leading other folks down the “I need a timezone” track.

This also raises a question about uncertainty. I appreciate that the
RFC distinguishes the nanosecond precision of the representation from
the resolution of the underlying clock. However, Clock::now() returns
only an Instant, with no way through that contract to convey the
source resolution or any available uncertainty information. I've had
servers lose access to their hardware clock due to hardware
malfunctions, so this is not just a theoretical concern. Where that
information is available, it should be preserved alongside the reading.
Where it is unknown, it should remain explicitly unknown. Printing nine
fractional digits cannot supply that information.

Uncertainty is likely not of interest to the average user or something
they understand: They just trust that their operating system provides
them with the correct time. For applications where this matters adding a
custom extension with a “ClockWithUncertainty” clock that returns the
Instant + a Duration would be the right choice. The current design is in
line with what virtually all the other programming languages do for
their standard library. Marc also suggested exposing clock_getres() on
the SystemClock, I'll reply there. In any case, I don't think this is
something that belongs on the Clock interface, since it increases the
API complexity for little benefit.

I think there are some things worth addressing in the current RFC:

1. Instant should throw when serialized to JSON. I understand the
   argument is that applications should choose their own representation,
   but the choice should be enforced rather than silently doing the wrong
   thing. Or provide an opaque serialization that can restore the
   Instant.

I discussed this with Derick and it's our position that:

1. As you mentioned and as I said in
   https://news-web.php.net/php.internals/132764 that there is no single
   canonical representation for JSON and that users need to make a choice
   themselves.
2. That implementing JsonSerializable just to always throw an
   exception would be misleading, because from the API surface it very much
   looks like JSON serialization would be supported.

That json_encode() includes a useless default serialization for
arbitrary objects instead of requiring an opt-in is something that
should be fixed in ext/json and not worked around for every (value)
object we implement. Since there is no “json decode to object”, an
opaque serialization that can restore the Instant is not really a
thing. If users need to manually call methods, they can just go via
ISO-8601.

2. DateTimeInterface is missing the toInstant() method, is that by
   design?

No. I just forgot that the interface exists. Now added.

3. The backward-compatibility section still says this RFC only
   introduces three new namespaced symbols. It should also cover the new
   methods on DateTime and DateTimeImmutable, including potential
   conflicts with existing subclass methods named toInstant().

Did some preliminary adjustments there. Might tune the phrasing later.

Best regards
Tim Düsterhus

7. get vs to

The RFC explicitly states that the Unix timestamp is not the internal
representation. getUnixTimestamp() is therefore a conversion, and by
the RFC's own convention (toIso8601DateTimeString(),
DateTime::toInstant()) it should be toUnixTimestamp(). Duration exposes
its components as properties, so with get*() we'd end up with a third
style within the same family.

I agree with this. $foo->toBar() is a very common "type conversion" pattern, and it makes sense to use here as well.

8. getUnixTimestamp() / getUnixTimestampMilliseconds()

Only the milliseconds variant names its unit, and microseconds (used all
over PHP: microtime(), DateTime) and nanoseconds are missing entirely. A
single pair taking the unit as an argument would cover all of them and
stay symmetric:

public static function fromUnixTimestamp(int $timestamp, TimeUnit
$unit = TimeUnit::Second): self;
public function toUnixTimestamp(TimeUnit $unit = TimeUnit::Second):
int;

TimeUnit would be an enum of Second, Millisecond, Microsecond and
Nanosecond, rounding towards negative infinity as already specified. The
current fromUnixTimestampSeconds($seconds, $nanoseconds) could remain alongside.

I would agree here as well.

13. A dedicated parser/formatter instead

I'd prefer parsing and formatting to live in a dedicated parser/formatter
API (future scope) rather than on Instant, where it would sit next to the
other ISO-8601 profiles and custom patterns. If the pair stays on Instant,
the name should say what it really is (a fixed RFC 3339-like profile), and
the grammar should be part of what we vote on.

I understand the tidiness/purity argument here, and I am generally sympathetic to it. However, that always needs to be balanced against usability. Any incoming date/time information to the PHP process is likely to be either an ISO-8601 string or a unix timestamp int. If we want people to convert those into Instants for doing manipulation and comparison on (which I presume is the case), then that needs to be ergonomically easy to do. Having to go through multiple parser/converter objects (which some purist is likely to insist be injected from a container rather than instantiated directly; I have been known to be that purist) to get there is not ergonomic. So if that logic is split off, we would need to be very careful to ensure the result is ergonomically simple and readily copy-pasteable.

14. until() vs Duration::between()

Was Duration::between(Instant $a, Instant $b) considered? Calculating a
duration feels like Duration's responsibility to me.

This also seems reasonable, as a named constructor of Duration.

--Larry Garfield

Hi

I think the following points still need some discussion. Some of
them may overlap with things others have already raised in this thread.
Rather than replying to each of those messages separately, I've
collected
everything in this one mail and mention who brought a point up where it
applies.

Thank you for the review. Derick and I already discussed some, but not
all of the points. For now I'll just reply to those that are resolved to
get them out of the way.

4. Configurable clock resolution

I'd like a way to configure the resolution,
e.g. a SystemClock that only ever returns whole seconds. Many consumers
(JWT iat/exp, HTTP dates, database columns) never want fractions.
A clock configured that way guarantees whole seconds to every consumer
it is injected into, instead of each consumer having to truncate on its
own. It also makes test expectations simpler, because the values never
carry
fractions.

We believe this is the job of a “Clock decorator”, e.g. CoarseClock
that takes in some clock and appropriately rounds or truncates the
Instant to the desired precision. Such a decorator would automatically
be compatible with any type of clock (e.g. a FrozenClock for testing).

As with the testing clocks, we consider a CoarseClock out of scope for
this RFC. With a possible future truncateTo() that I already mentioned
elsewhere in the discussion, a userland implementation would become
trivial for the use cases where a coarser clock is required.

7. get vs to

The RFC explicitly states that the Unix timestamp is not the internal
representation. getUnixTimestamp() is therefore a conversion, and by
the RFC's own convention (toIso8601DateTimeString(),
DateTime::toInstant()) it should be toUnixTimestamp(). Duration exposes
its components as properties, so with get*() we'd end up with a third
style within the same family.

Good catch, we renamed the methods to use the to prefix.

9. getNanoseconds()

It isn't obvious whether this returns the nanoseconds since epoch or
the
nanoseconds within the current second. getNanoOfSecond() (Java's
NANO_OF_SECOND) would remove that ambiguity.

We believe that with the renaming of the “Unix timestamp” converter to
use the to prefix and the lack of “Unix” in the name of
getNanoseconds() the naming is clear enough. It is also easy to see
that the result of getNanoseconds() can't be the number of nanoseconds
elapsed since the Unix epoch, because the value is guaranteed to be less
than 1_000_000_000 (i.e. less than 1 second). Using nanoseconds as the
fractional part is consistent with Duration::$nanoseconds.

For completeness I'd like to note that the epoch of the Instant is
intentionally left unspecified and that the Unix epoch is just one of
several possible epochs.

Best regards
Tim Düsterhus