[RFC] Duration class

Hi

Am 2026-06-18 16:18, schrieb Seifeddine Gmati:

• Is there a reason the highest unit is seconds not hours?

The highest unit supported by the constructors is hours
(Duration::fromHours()). The internal representation uses a seconds +
nanoseconds pair for the reasons outlined in the design considerations,
similarly to Rust’s and Java’s Duration. 68 years on 32-bit systems and
21× the age of the universe on 64-bit systems should be plenty.

• The RFC specifies Duration::fromIso8601String, but there does not
  seem to be a method to turn the duration itself back into an ISO 8601
  string. is there a reason for that?

The best reason there probably is “the proposed API is intentionally
minimal”.

There are probably also some decisions to be made for the
re-stringification into ISO-8601: Should it stringify straight into
sprintf("PT%d.%09dS", $seconds, $nanoseconds) or should it try to use
“as large units as possible” (i.e. minutes and hours). The correct
answer might depend on the use case and thus it's probably better to
move this decision to the PHP 8.7 cycle :-)

• I think it would be nice to have methods that return the total
  duration as a specific unit as a floating point, e.e.g.,
  getTotalSeconds(), was this considered?

Derick and I haven't discussed this, but the “minimal API” applies here
as well. Floating point versions we specifically left out (for now),
because we didn't want to go into the precision / rounding question. As
an example how many nanoseconds should 1.4 be? The internal
representation of that float is 1.3999999999999999.

Best regards
Tim Düsterhus

Hi

Am 2026-06-18 22:25, schrieb Frederik Bosch:

Rather than building a whole new date/time library, did you consider
using the temporal_rs library instead? This library is used for the new
Temporal API that is now available in Firefox and Chrome and is
a browser standard.

We did not look specifically at temporal_rs (I wasn't aware of its
existing until now), but we looked at JavaScript’s Temporal API -
amongst others.

I'm not speaking for Derick here, but I do not believe it is possible to
just take an API that was built for a different programming language and
plug it into a different programming language without making any
changes. Different programming languages have different capabilities,
ecosystems and code styles and without adjusting the API to the
respective language, it will just stick out like a sore thumb.

As an example, JavaScript’s Temporal.Duration.prototype.round is an
overloaded function with one overload taking an “options object”. This
is something that works well with JavaScript’s dynamic nature, but is
something we are moving away from in PHP, because it doesn't interact
well with explicit type-checked signatures that are a first-class
citizen in PHP. Semantically PHP is much closer to Java than it is to
JavaScript and I believe that Java’s java.time.* is a comparatively
better fit than JavaScript’s Temporal, but even that cannot be taken
as-is, because Java supports overloaded methods (e.g.
java.time.Duration.minus()) whereas PHP does not.

The complicated part here is the API design, not the internal
implementation, particularly since PHP already has a date API that
supports all the relevant operations. It's just that the userland API
really starts to show its age. So using temporal_rs under the hood,
while exposing a PHP-specific API will not provide any meaningful
benefit - and would on the contrary add a new dependency on Rust. I'm
not saying that including Rust is a bad idea, but integrating Rust
libraries nicely into the Zend Engine, for example to make them work
with PHP’s memory_limit would be a significant undertaking by itself
and not be something we can just do as a “don’t worry about it”
implementation detail.

Best regards
Tim Düsterhus

Hi

Am 2026-06-19 18:17, schrieb Larry Garfield:

My main suggestions would be for more constructors, though I'm sure
that's going to get a response of "MVP, add later." :-P

Well, you would need to explain what constructors you are missing out
on. If it's something “obviously correct and we are not going to regret
it” I wouldn't necessarily rule out adding them straight away. But
otherwise your suspicion would be correct.

My main pushback, I think, is the fromIso8601String() method, which is
not at all self-descriptive. Presuming it means the format accepted by
DatePeriod (give or take bugs), that's not self-evident anywhere in the
RFC, or the method name.

The doc comment for the method explains “Parse a ISO-8601 period.” and
even the automated AI summary in Google (almost) correctly tells right
away “An ISO-8601 period (or duration) represents an amount of time
using the format P[n]Y[n]M[n]W[n]T[n]H[n]M[n]S.” There is a small
mistake in there in that T doesn't have a preceding [n], but it
gives the correct idea of what is being expected there. And of course
all the search results point towards the same thing.

I can easily see people who aren't familiar with that period format
(which is, I suspect, most people) trying to use "5:23:44" or similar
human time formats instead, which will break. But that format actually
feels more useful, and is also defined somewhere in ISO8601 (as part of
the full date/time string if nothing else), so the method name is
ambiguous.

“break” is a strong word there. It will be rejected with a ValueError
as an invalid input.

I think we do need to come up with a better, more self-documenting name
for that operation, and consider if we also want a
fromHumanTimeString() that accepts "5:23"44" type strings.

Without checking with Derick, I would be open to renaming the method to
fromIso8601PeriodString(). While that would be quite long, (fuzzy)
auto-completion should handle that. And I suspect that constructor would
also be used comparatively rarely.

If that name makes sense to you, I'll discuss all the feedback (also
from the other mails) that I didn't outright reject myself with Derick
in bulk in the next days :-)

The “from human time” one I would reject outright, because of the
ambiguity with regard to how fractional seconds are represented. In the
wild I've sometime seen . as the separator between seconds and
fractional seconds, but also :, which means that the format would be
ambiguous. And I'm sure there are also going to be differences between
languages, just like some countries use 24h formats and others use 12h.
And then of course, what even is a “human time”. And with regard to the
flexibility in inputs that strtotime() accepts, is "12 hours and 45 seconds" a “human time”? Is "12.5h" a “human time”? Is "500µs" a
“human time” (notably the µ character is not in 7-bit ASCII)?

Best regards
Tim Düsterhus

Thanks for being this up. I think that's a sensible approach and can be
used as a starting point for further improvements to the date/time API.

Some comments though:

4. You have some operator methods defined (+add, -sum, /multiplyBy,
   <>=compare, what about other operators?

What would those be? Personally I'd want to see operators for add and sub, at least, but I'm not sure what else would be useful.

5. Did you thought of supporting float on the initializer methods?

Floats introduce all the complexity and lack of precision of, well, floats. Best to avoid them.

6. You should at least mention that this class works with a fixed
   definition of e.g. how long a minute is - no leaps tz handling here.
   Which is the correct approach for it.

7. Naming consistency ... add/sub vs. multiplyBy. Why not
   addBy/sub[tract]By or multiply to be more consistent?

I concur here.

8. negative vs. isNegative

9. negate() I would expect to get back a negative Duration. Also, it
   sounds like modifying the duration but I'm assuming a new instance gets
   returned. What about inverted()?

Good point. negated() would be fine, I think. (As noted elsewhere, sort() vs sorted() is a very common pattern for "modify in place" vs. "make new", across a number of languages.)

--Larry Garfield

Hi

Am 2026-06-19 18:26, schrieb Marc B.:

1. Why seconds is always positive with separate negative boolean? I
   don't get the reason behind that logic and it puts additional effort on
   the user reading these values. A negative Duration should just be
   negative seconds. Nanoseconds on the other hand should always between 0
   and 999_999_999.

This is answered in the “design considerations” section of the RFC. Did
you miss that one? With regard to your specific suggestion of only the
seconds should be negative: How do you represent a Duration of negative
0.5 seconds then?

2. fromIso8601String should just be fromIso8601. The name implies a
   string already and the argument type defines it as well.

See my sibling reply to Larry with regard a possible rename. With regard
to the String suffix specifically. I find it important for several
reasons:

• Horizontal consistency with Dom\HTMLDocument::createFromString()
  (which also has createFromFile() with an identical signature).
• The lack of method overloading. There could possibly be an ISO-8601
  object that might require a slightly different signature so that a
  simple union type is insufficient.
• Just “from ISO-8601” sounds like an incomplete sentence (and “from
  ISO-8601 period” does as well). I would add the “string” part in my
  spoken communication as well, so I feel it should also be there in the
  method name.

3. fromSeconds is the only initiator with a second nanoseconds
   argument. That feels a bit inconsistent from consistency POV.

See “design considerations”.

Also, it's not just applying these values because, to be valid, there
needs to be some calculation be done.

This is incorrect, as demonstrated by the proof-of-concept userland
implementation.

4. You have some operator methods defined (+add, -sum, /multiplyBy,
   <>=compare, what about other operators?

What are you looking for?

5. Did you thought of supporting float on the initializer methods?

See the sub-thread started by Seifeddine.

6. You should at least mention that this class works with a fixed
   definition of e.g. how long a minute is - no leaps tz handling here.
   Which is the correct approach for it.

I believe the “Introduction” section (and the non-normative userland
implementation) was pretty clear on that the class represents
“stop-watch time”, not something related to clocks. But for completeness
I have just added a PHPDoc comment to that effect to the class itself
(in addition to the existing PHPDoc on the methods).

7. Naming consistency ... add/sub vs. multiplyBy. Why not
   addBy/sub[tract]By or multiply to be more consistent?

I don't think “add by” and “sub(tract) by” is correct grammar. The By
on divideBy was a deliberate choice to make it clear that the Duration
is the dividend and the given integer is the divisor, because this isn't
entirely clear using use divide. For multiplication as the inverse of
division we added it for consistency (even though it doesn't matter
there, because multiplication is commutative).

This also roughly matches Java's naming of multipliedBy / dividedBy
and plus / minus.

8. negative vs. isNegative

Please provide a concrete suggestion.

9. negate() I would expect to get back a negative Duration. Also, it
   sounds like modifying the duration but I'm assuming a new instance gets
   returned. What about inverted()?

The class is readonly, so yes, a new instance gets returned.
negated() is also something I thought of, which would also work with
multipliedBy() and dividedBy() as in Java, but (as not a native
speaker of English) I believe this naming pattern breaks down for the
addition / subtraction. Ignace's suggestion of just having sum() might
solve this, though.

10. On assuming the duration is immutable. Does the medifier function
    still return the same object for the same resulting durations?

I don't understand the question.

I have spend quite some time experimenting with building a good
date/time API matching PHP. What I came up with went into an
experimental but already working library in PHP without using the
available date/calendar extension.
https://github.com/marc-mabe/php-timelib

Yes, that repository is referenced in the backwards incompatible changes
section.

Best regards
Tim Düsterhus

Hi

Am 2026-06-22 10:42, schrieb Ilija Tovilo:

The Time\Duration class will also implement internal “comparison
handlers”, which means that direct comparisons with operators such as
< will work.

Can you explicitly spell out that this does not apply to arithmetic
operators?

Yes. I added “Other operators (such as + for addition) will not be
overloaded.”.

One thing worth specifying is how you're planning on handling the
passing of Duration objects to APIs that do not support certain
precisions. For example, PHPs sleep() is a thin wrapper around system
sleep(), which only accepts seconds. This would internally need to be
re-routed to usleep(), but even then usleep() only supports
microseconds. What happens when we pass a duration of that scale to
sleep()? Throw? Truncate? Round? (Let's disregard the existence of
nanosleep() for the sake of the argument.)

The behavior would be left up to the API in question, because it is in
the best position to determine which makes the most sense. As an
example, a function like sleep() cannot sleep for exact durations
anyways, because the computer might be busy running another process when
it is supposed to wake up. Here it might make sense to always round up
to the nearest microsecond, which would be in line with existing
expectations of sleeping for at least the given amount of time.

If something is fundamentally limited to a second-granularity - which I
expect to be comparatively rare nowadays - it might make sense to just
not accept a Time\Duration object and instead keep using a plain
integer - which still in a way be compatible with Time\Duration by the
developer explicitly only retrieving $duration->seconds and passing it
along.

In other situations throwing might be appropriate, particularly when the
Time\Duration is “too long” to be meaningfully handled (e.g.
Time\Duration::fromSeconds(PHP_INT_MAX)).

Within the internal API we plan to make it easy to turn a
Time\Duration object into a struct timespec, which is a “lossless”
conversion and thus it would immediately compatible with anything taking
a struct timespec.

In the future I could imagine a userland method that takes a
RoundingMode and allow to round a Duration to millis / micros /
seconds.

I have added a short “Passing Duration objects to APIs unable to handle
nanosecond precision” section summarizing the above.

The biggest concern for me is having to instantiate an object for all
calls that take a duration, which seems like mostly unnecessary
overhead. This is partially resolvable by adding support for storing
immutable objects in shared memory, which works here because the class
is readonly.

Given the class only exposes named constructors, it should be feasible
to include a small LRU cache to efficiently handle situations like the
following:

 for (;;) {
     $watchers = $poll->wait(Duration::fromMilliseconds(500));

     foreach ($watchers as $watcher) {
         /* … */
     }
 }

where the same timeout is repeatedly being used. I consider this kind of
optimization to be a implementation detail that is not worth spelling
out in the RFC, but it is good that you raised it for discussion.

Best regards
Tim Düsterhus

Hi

Am 2026-06-23 02:36, schrieb Peter Stalman:

1. Are there other classes planned for the \Time namespace? I think
   we

Yes, see also the “Future Scope” section.

should avoid using root namespaces and instead decide on a common
namespace, so something like \Std\Time or \Php\Time. Although I
realized that topic is a bit above this particular RFC, but worth
considering for internals as more root namespaces are added.

The use of the namespace is in line with the namespace policy that you
can find at
https://github.com/php/policies/blob/main/coding-standards-and-naming.rst#namespaces.
It was (almost) unanimously accepted in 2021:
https://wiki.php.net/rfc/namespaces_in_bundled_extensions.

This policy has been the basis of Random* (8.2), Dom* (8.4), Uri*
(8.5).

2. Since the class is marked final (why?), I would recommend we also
   create
   a DurationInterface and use that as the type wherever it is used.
   This
   would alleviate some of the concerns people have with making it final.
   For
   example, see popular packages like \Carbon\Carbon extends \DateTime
   and
   implements \DateTimeInterface.

It's a value object, there is only one reasonable implementation that
preserves all the invariants that users expect. This topic has
previously also been discussed as part of the URI extension (somewhere
here: https://news-web.php.net/php.internals/123997).

Best regards
Tim Düsterhus