The Time\Duration class

Intro

Represents a fixed length of elapsed time, such as a timeout or the time measured by a stopwatch, with nanosecond precision. A duration consists of a non-negative number of whole Time\Duration::$seconds, a number of Time\Duration::$nanoseconds below one second, and a sign stored in Time\Duration::$negative.

Unlike DateInterval, a Time\Duration does not have calendar units such as days, months or years, because those do not map to a fixed number of seconds: a day can be 23 or 25 hours long across a DST transition, and months have different lengths. The largest unit a duration can be created from is therefore the hour. Use DateInterval for calendar arithmetic on DateTimeImmutable objects, and Time\Duration for unambiguous amounts of time, for example the timeout of the I/O polling API.

Objects of this class are immutable. They are created with one of the Time\Duration::from*() factory methods, and every operation such as Time\Duration::add or Time\Duration::multiplyBy returns a new object instead of modifying the existing one. A duration can be negative, which is typically the result of Time\Duration::sub or Time\Duration::negate. A duration of zero is never negative.

Two durations can be compared with the comparison operators (<, <=, ==, !=, >=, > and <=>) as well as with Time\Duration::compare. The arithmetic operators are not supported; use the methods of this class instead.

The maximum length of a duration is 9223372035 seconds, roughly 292 years, on 64-bit platforms, and 2147483647 seconds, roughly 68 years, on 32-bit platforms. Any operation whose result would exceed this range throws a Time\TimeException.

Class synopsis

TimefinalreadonlyDurationPropertiespublicreadonlyintsecondspublicreadonlyintnanosecondspublicreadonlyboolnegativeMethods

Properties

seconds

The number of whole seconds, without the sign. This is always greater than or equal to 0, and at most 9223372035 on 64-bit platforms or 2147483647 on 32-bit platforms.

nanoseconds

The fraction of a second in nanoseconds, without the sign. This is always between 0 and 999999999, inclusive.

negative

Whether the duration is negative. The sign applies to the duration as a whole, so a negative duration of one and a half seconds has seconds set to 1, nanoseconds set to 500000000, and negative set to true. A duration of zero always has this set to false.

Examples

Creating and combining durations

<?php
$timeout = \Time\Duration::fromMinutes(1)->add(\Time\Duration::fromMilliseconds(1500));

var_dump($timeout);
printf("%d.%09d seconds\n", $timeout->seconds, $timeout->nanoseconds);

The above example will output:

object(Time\Duration)#3 (3) {
  ["seconds"]=>
  int(61)
  ["nanoseconds"]=>
  int(500000000)
  ["negative"]=>
  bool(false)
}
61.500000000 seconds

Comparing durations

<?php
$durations = [
    \Time\Duration::fromMinutes(2),
    \Time\Duration::fromMilliseconds(250),
    \Time\Duration::fromSeconds(5),
];

usort($durations, \Time\Duration::compare(...));

foreach ($durations as $duration) {
    printf("%d.%09d\n", $duration->seconds, $duration->nanoseconds);
}

var_dump(\Time\Duration::fromMinutes(1) > \Time\Duration::fromSeconds(59));
var_dump(\Time\Duration::fromSeconds(1) == \Time\Duration::fromMilliseconds(1000));

The above example will output:

0.250000000
5.000000000
120.000000000
bool(true)
bool(true)

See Also

• DateInterval
• hrtime()

Duration