Re: [RFC] Duration class

On Thu, 18 Jun 2026 at 14:48, Tim Düsterhus <tim@bastelstu.be> wrote: > > Hi > > Derick and I are proposing the introduction of a new > Time\Duration > class to represent “stop-watch” or “egg-timer” durations to improve the > developer experience for APIs taking a timeout. We are specifically > targeting PHP 8.6 for this RFC, since part of the motivation is > improving the API of the new “Polling API” that already landed in PHP > 8.6 (https://wiki.php.net/rfc/poll_api) before the “backwards > compatibility” door closes with the feature freeze in two months. > > This RFC is also intended to be a first part of a modernized date and > time API in PHP, while being useful on its own. To that extent and given > the deadline we hope to make, the proposed API is intentionally minimal > and focused on functionality that we are relatively certain to: > > 1. Be correct, or > 2. be requirement for future additions that cannot later be added > without breaking compatibility. > > We would therefore ask to keep the discussion focused on actual issues > rather than additional “convenience functionality” that might require > extensive discussion or thought. > > All that said, you can find the RFC at: > https://wiki.php.net/rfc/duration_class. It hopefully includes > all the > important explanation and also provides a rationale as to why we made > the design decisions we made. > > Best regards > Tim Düsterhus Hi Tim, Thank you for proposing this! I think it would be a good addition, and a move in the right direction for a better built-in date-time stuff. I do have some questions: - Is there a reason the highest unit is seconds not hours? - 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? - 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? Also, i wanted to point out Psl\DateTime\Duration that is basically the same thing: https://github.com/php-standard-library/php-standard-library/blob/next/packages/date-time/src/Psl/DateTime/Duration.php#L37 which was modeled after Rust's std::time::Duration ( https://doc.rust-lang.org/beta/std/time/struct.Duration.html ) and Java's Duration ( https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html ). Cheers, Seifeddine.