Re: [RFC] Duration class

Hi On 7/3/26 22:17, Marc B. wrote:

The fromSeconds constructor breaks the flow of all other constructors as this is not only about seconds. Also, this directly exposes how it's handled internally to the API which makes it hard to extend later on (maybe we want to support picoseconds on 10 years).

“Nanosecond precision” is an integral part of the design of the class and folks will build assumptions around this. Changing the precision later will be something between hard to impossible, even if the fromSeconds() constructor wouldn't take a fractional part. This is a property shared between all the other languages we looked at (except for Swift as mentioned by John Bafford): Everyone models their Durations with nanosecond precision and documents it as such.

PHP should make things simpler - not more complex. There are plenty of different duration systems out there a such values could come from as input to a PHP application. The current Duration API forces you to manually correctly calculate the value before passing it the constructor. E.g.: * time measurement using microtime(true) * using hrtime(true) returns float on 32bit

For both of these, the false variant returns the value as a fixed-point decimal of seconds + fractional seconds, matching the “seconds with a fractional part” design of this RFC. For hrtime() specifically, you can even do the following:

    $duration = Duration::fromSeconds(...hrtime());

which will do the right thing (except for the fact that hrtime() *technically* returns an Instant [1], not a Duration). And of course the new date and time API would not be complete without also providing access to a high-precision (monotonic) clock in a way that cleanly interoperates with the new API. [1] An instant with an unknown origin.

I like the idea of a general "from" constructor - but not restricted to seconds + nanos but ALL supported units

This one could still be provided in future scope, but given my previous replies, you can probably assume that I don't consider it a good idea.

$seconds = 1; $millis = 1_000; $micros = 1_000_000; $nanos = 1_000_000_000; Duration::from(seconds: $seconds, milliseconds: $millis, microseconds: $micros, nanoseconds: $nanos); // 4 seconds - yes please

I'd argue that if I have the use case of constructing a duration from a number of seconds *and* multiple different fractions of a second that each could overflow into larger scales, I should likely stop and consider whether what I'm doing is a good idea. But even then:

    Duration::fromSeconds($seconds)
        ->add(Duration::fromMilliseconds($millis))
        ->add(Duration::fromMicroseconds($micros))
        ->add(Duration::fromNanoseconds($nanos));

will work and do the right thing. For the common case of “seconds + fractional seconds”, the fromSeconds() constructor works (and going from fractional milliseconds to fractional nanoseconds is a *1_000_000 operation that should be easy and obvious enough).

... there must be at most one way of creating a Duration with a specific length from any given constructor. This is in order to make it easy to reason about the resulting value, without needing to perform (mental) calculations. It makes it simple to reason about for you as implementing it - it forces the burden to the one using the API.

The quoted paragraph is speaking from the perspective of a user using the API. In the internal implementation just ignoring component overflow would be easier than checking for it. Best regards Tim Düsterhus