README

Working with durations made easy.

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

• Installation
• Reference
  • Supported Input Values
  • Transformations
  • Comparisons
  • Operations
• Roadmap

Installation

You can install the package with Composer:

composer require gamez/duration

You can then use Duration:

<?php
use Gamez\Duration;

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

Reference

Supported input values

DateIntervals

use Gamez\Duration;

Duration::make('PT13M37S');
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');

Transformations

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"

Comparisons

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]

Operations

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

Roadmap

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