Re: [RFC] Duration class

Hi On 03.07.26 23:51, Tim Düsterhus wrote:

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.

This is a simplified example what I mean: // Initial version final class Duration {

    public readonly $totalSeconds;
    public int $milliseconds { get => (int)($this->microseconds / 1_000); } // 0 - 999
    public readonly $microseconds; // 0 - 999_999
    public static function from(/* ... */ int $seconds=0, int $milliseconds=0, int $microseconds=0)

} // Next version - introduce nanoseconds final class Duration {

    public readonly int $totalSeconds;
    public int $milliseconds { get => (int)($this->nanoseconds / 1_000_000); } // 0 - 999
    public int $microseconds { get => (int)($this->nanoseconds / 1_000); } // 0 - 999_999
    public readonly int $nanoseconds; // 0 - 999_999_999
    public static function from(/* ... */ int $seconds=0, int $milliseconds=0, int $microseconds=0, int $nanoseconds=0)

} // Next version - introduce picoseconds final class Duration {

    public readonly int $totalSeconds;
    public int $milliseconds { get => (int)($this->picoseconds / 1_000_000_000); } // 0 - 999
    public int $microseconds { get => (int)($this->picoseconds / 1_000_000); } // 0 - 999_999
    public int $nanoseconds { get => (int)($this->picoseconds / 1_000); } // 0 - 999_999_999
    public readonly int $picoseconds; // 0 - 999_999_999_999
    public static function from(/* ... */ int $seconds=0, int $milliseconds=0, int $microseconds=0, int $nanoseconds=0, int $picoseconds=0)

} Introducing nanoseconds and later on picoseconds in that example isn't a big deal anymore.

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.

Why would you create a duration directly from a point-in-time ?

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.

The same applies to the nanoseconds argument of your fromSeconds() Duration::fromSeconds($seconds)->add(Duration::fromNanoseconds($nanos))

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).

The hole point is to not need to manually calculate before and manually make sure it's in the expected range of the limited Duration constructor. // not tested and I still might miss a case - but this should give a mental modal what you need to manually handle for such a simple function function durationFromInput(int $seconds, int $microseconds): Duration {

    if ($microseconds > 999_999 || $microseconds < -999_999) {
        $seconds += intdiv($microseconds, 1_000_000);
        $microseconds = $microseconds % 1_000_000;
    }

    if ($microseconds < 0) {
        $seconds -= 1;
        $microseconds = 1_000_000 - $microseconds;
    }

    $negative = $seconds < 0;
    if ($negative) {
        $seconds *= -1;
    }

    if (is_float($seconds)) {
        throw new RangeError('Integer overflow');
    }

    $duration = Duration::fromSeconds($seconds, $microseconds * 1_000);
    if ($negative) {
        $duration = $duration::negate();
    }

    return $duration;

}

Best regards Tim Düsterhus