Re: [RFC] Duration class

Hi Tim, Am 18. Juni 2026 15:47:57 MESZ schrieb "Tim Düsterhus" <tim@bastelstu.be>: >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. 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: 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. 2. fromIso8601String should just be fromIso8601. The name implies a string already and the argument type defines it as well. 3. fromSeconds is the only initiator with a second nanoseconds argument. That feels a bit inconsistent from consistency POV. Also, it's not just applying these values because, to be valid, there needs to be some calculation be done. 4. You have some operator methods defined (+add, -sum, /multiplyBy, <>=compare, what about other operators? 5. Did you thought of supporting float on the initializer methods? 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? 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()? 10. On assuming the duration is immutable. Does the medifier function still return the same object for the same resulting durations? 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> PS: don't use in product PS 2: A working group for that would be great 😃 Regards, Marc