Re: [PHP-DEV] [RFC] Duration class

On Mon, Jun 29, 2026 at 10:16 PM Tim Düsterhus <[email protected]> wrote:

> Hi
>
> Am 2026-06-22 19:37, schrieb Tim Düsterhus:
> >> Oof. Naming.
> >> The only term I can find that is specifically about dividing one
> >> duration by another is "beat", but that's definitely domain-specific.
> >>
> >> 'periodCount' or 'countPeriods' come to mind. Since in 'n/d' we're
> >> counting how many times duration 'd' occurs during duration 'n' we're
> >> basically multiplying the duration by frequency '1/d'; the inverse of
> >> the frequency - 'd' itself - is called the period. Which word is also
> >> used for "named subdivision of historical time", "class-sized
> >> subdivision of a school day", and so on.
> >>
> >> The biggest hangup with that name is that it doesn't explicitly state
> >> that it returns the remainder as well. periodParts? periodDivide?
> >
> > Thank you for the suggestions. I quite like period. I'll also check
> > with Derick if he has any good ideas (and regarding the Duration
> > divided by Duration bit in general).
>
> Derick mentioned how “period” might not be an ideal term, because it's
> something that the ISO standard moved away from. After having chatted
> with him about this, I would agree that it would possibly be confusing
> to mix “technical terminology” with “colloquial terminology” and might
> raise questions about what the difference between “Duration” (class
> name) and “Period” (method name) is when other languages call “Period”
> what we call “Duration”.
>
> For `chunked…()` as suggested elsewhere in the thread, the implied
> return type would be `list<Duration>` (i.e.
> Duration::fromMinutes(50)->chunkedBy(Duration::fromMinutes(20)) ===
> [Duration::fromMinutes(20), Duration::fromMinutes(20),
> Duration::fromMinutes(10)]`), since that would be consistent with
> `array_chunk()` and chunking in other programming languages.
>
> Unless we come up with a genius idea, we might defer both divisions to
> later and ship PHP 8.6 with just addition, subtraction and
> multiplication - for that the question of add/sub vs sum() would still
> be open (see: https://news-web.php.net/php.internals/131504).
>
> Best regards
> Tim Düsterhus
>

How about this

Duration::fromHours(5)->dividedBy(5); //returns  Duration::fromHours(1);
and
Duration::fromHours(50->dividedInto(Duration::fromHours(1)); // returns
['factor' => 5, 'remainder' => Duration::fromSeconds(0)];

Duration::dividedInto in my example returns an array but I would have no
issue if it would return a DTO instead.
This way the naming seems easy to remember IMHO

- "by" -> integer,
- "into" -> duration

and it reads naturally I think.

Best regards,
Ignace