Skip to content
🚀 PHP 8.6 is coming — check out what's new
PHP News
Search
Implemented PHP 8.6

Duration class

Adds a Time\Duration class that stores stopwatch-style time with nanosecond precision, for timeouts and delays instead of bare ints or floats.

Implement the Time\Duration class as outlined in the RFC?

Primary vote · 2/3 majority

35 Yes 1 No 2 abstain 97% approval

This poll has closed.

Should the mathematical operation methods of Time\Duration use full or abbreviated names?

· 2/3 majority

  • Abstain 3
  • mul, divBy, neg, abs 2
  • multiplyBy, divideBy, negate, absolute 30

This poll has closed.

Accepted. The main vote passed 35 to 1 with 2 abstaining, well over the two-thirds majority it needed.

A second vote settled the method names. Full names like multiplyBy and divideBy beat abbreviations like mul and divBy by 30 to 2, with 3 abstaining.

Both votes closed on July 31, 2026. The RFC targets PHP 8.6, and the implementation has been merged.

Summary

PHP has no consistent way to express "this much time." Some functions take seconds as an int, others take milliseconds, and some split seconds and microseconds into two parameters. A few use a float, which can lose precision. This RFC from Tim Düsterhus and Derick Rethans adds a Time\Duration class that stores a length of time the way a stopwatch would, down to the nanosecond.

Why not DateInterval

DateInterval can hold days and months, and those don't map to a fixed number of seconds. A month has anywhere from 28 to 31 days, and a day can be longer or shorter when clocks change for daylight saving time. A Duration only goes up to hours, so its length is always exact.

Show me

Here is a trimmed version of the RFC's example:

use Time\Duration;

$oneSecond = Duration::fromSeconds(1);
$halfSecond = $oneSecond->divideBy(2);
$onePointFiveSeconds = $oneSecond->add($halfSecond);

$negativeHour = Duration::fromHours(1)->negate();

$baseDelay = Duration::fromMilliseconds(100);
$delay = $baseDelay->multiplyBy(2 ** 5); // 3.2 seconds

You create a Duration with a named constructor for the unit you want: fromSeconds(), fromNanoseconds(), fromMicroseconds(), fromMilliseconds(), fromMinutes() or fromHours(). You can also parse an ISO 8601 duration string with fromIso8601DurationString().

How it works

  • The class is final and readonly, and every method returns a new object.
  • It has three properties: $seconds, $nanoseconds and $negative.
  • The math methods are add(), sub(), multiplyBy(), divideBy(), negate() and absolute().
  • Duration::compare() returns -1, 0 or 1. Comparison operators like < also work, but arithmetic operators like + don't.
  • Overflows throw a new Time\TimeException.
  • It can represent about 292 years.

The RFC doesn't change existing functions like sleep() to accept a Duration. The one exception is the new polling API, also planned for PHP 8.6, whose wait() method takes a ?Time\Duration $timeout instead of two numeric parameters.

The authors describe this as the first piece of a new date and time library for PHP.

What it means for existing code

Nothing breaks, since everything lives in a new Time namespace. A GitHub search found only 7 projects with their own Time\Duration class, and two of those were polyfills aimed at the same problem.

Our coverage