Working with durations made easy

4.2 2020-12-19 20:15 UTC

This package is auto-updated.

Last update: 2021-01-21 11:23:59 UTC


Working with durations made easy.

Current version Supported PHP version Code Coverage Sponsor

Do you like to use DateInterval to compute and work with durations? Me neither, so let's fix that!


You can install the package with Composer:

composer require gamez/duration

You can then use Duration:

use Gamez\Duration;

$duration = Duration::make('13 minutes 37 seconds');
// or start with nothing
$duration = Duration::none();


Supported input values


use Gamez\Duration;

Duration::make(new DateInterval('PT13M37S'));

Colon notation

use Gamez\Duration;

Duration::make('13:37'); // minutes:seconds
Duration::make('13:37:37'); // hours:minutes:seconds

Textual notation

A textual notation is any value that can be processed by DateInterval::createFromDateString()

use Gamez\Duration;

Duration::make('13 minutes 37 seconds');


When transformed, a Duration will be

  • converted to a DateInterval representation
  • optimized in the sense that an input value of 60 seconds would result in an output value of "1 minute", for example "PT60S" would be converted to "PT1H"
use Gamez\Duration;

$duration = Duration::make('8 days 29 hours 77 minutes');

echo (string) $duration; // P9DT6H17M
echo json_encode($duration); // "P9DT6H17M"


use Gamez\Duration;

$oneSecond = Duration::make('1 second');
$sixtySeconds = Duration::make('60 seconds');
$oneMinute = Duration::make('1 minute');
$oneHour = Duration::make('1 hour');

$oneSecond->isSmallerThan($oneMinute); // true
$oneHour->isLargerThan($oneMinute); // true
$oneMinute->equals($sixtySeconds); // true

$durations = [$oneMinute, $oneSecond, $oneHour, $sixtySeconds];

usort($durations, function ($a, $b) {
    return $a->compareTo($b);
}); // -> [$oneSecond, $sixtySeconds, $oneMinute, $oneHour]


Results will always be rounded by the second.

use Gamez\Duration;

$thirty = Duration::make('30 seconds');

echo $thirty->withAdded('31 seconds'); // PT1M1S
echo $thirty->withSubtracted('29 seconds'); // PT1S
echo $thirty->multipliedBy(3); // PT1M30S
echo $thirty->dividedBy(2.5); // PT12S

$thirty->multipliedBy(-1); // InvalidArgumentException
$thirty->withSubtracted('31 seconds'); // InvalidArgumentException


  • Support more input formats
  • Add "output for humans" (like colon notation)
  • Support precision (similar to spatie/period)
  • ...