Period

This is the documentation for version 4.0 which will be supported until TBD. Please consider upgrading your code to the latest stable version

The Duration class

The Duration class is introduced in version 4.2.

A duration is the continuous portion of time between two datepoints expressed as a DateInterval object. The duration cannot be negative.

The Duration class is introduced to ease duration manipulation. This class extends PHP’s DateInterval class.

Constructors

Duration::create

Since version 4.5 chronometer format is supported.

public Duration::create($duration): self

Converts its single input into a Duration object or throws a TypeError otherwise.

parameter

$duration can be:

WARNING: When the string is not parsable by DateInterval::createFromDateString a DateInterval object representing the 0 interval is returned as described in PHP bug #50020.

Examples

use League\Period\Duration;
use League\Period\Period;

Duration::create('1 DAY');                  // returns new Duration('P1D')
Duration::create(2018);                     // returns new Duration('PT2018S')
Duration::create('PT1H');                   // returns new Duration('PT1H')
Duration::create(new DateInterval('PT1H')); // returns new Duration('PT1H')
Duration::create('12:30');                  // returns new Duration('PT12M30S')  
Duration::create(new Period('now', 'tomorrow'));
// returns (new DateTime('yesterday'))->diff(new DateTime('tomorrow'))

Duration::createFromDateInterval

Since version 4.11.

You can specifically instantiate a Duration instance from a DateInterval instance. This feature was already supported via the Duration::create method but it is now accessible stand alone.

Examples

use League\Period\Duration;

$interval = new DateInterval('PT30H5S');
Duration::createFromDateInterval($interval);  

Duration::createFromChronoString

Since version 4.11.

You can specifically instantiate a Duration instance from a timer like string format +/-HH:MM::SS.FFFFFF. This feature was already supported via the Duration::create method but is now accessible stand alone.

The hour and fraction units are optional

Examples

use League\Period\Duration;

Duration::createFromChronoString('12:30');      // returns new Duration('PT12M30S')  
Duration::createFromChronoString('12:30:34.8'); // returns new Duration('PT12H30M34.8S')

On error a League\Period\Exception will be thrown.

Duration::createFromTimeString

Since version 4.11.

You can specifically instantiate a Duration instance from a time string format in accordance with ISO8601 +/-HH:MM::SS.FFFFFF. This feature differs from Duration::createFromChronoString method by requiring the presence of at least the hour and the minute unit.

The second and fraction units are optionals

Examples

use League\Period\Duration;

Duration::createFromTimeString('12:30');      // returns new Duration('PT12H30M')
Duration::createFromTimeString('12:30:34.8'); // returns new Duration('PT12H30M34.8S')

On error a League\Period\Exception will be thrown.

Duration::createFromSeconds

Since version 4.11.

You can specifically instantiate a Duration instance from seconds with optional fractions. This feature was already supported via the Duration::create method but it is now accessible stand alone.

Examples

use League\Period\Duration;

Duration::createFromSeconds(28.5); // returns Duration::createFromDateString('28 seconds 500000 microseconds')  

Default constructor

The constructor supports fraction on the smallest value.

For instance, the following is works while throwing an Exception on DateInterval.

use League\Period\Duration;

$duration = new Duration('PT5M0.5S');
$duration->f; //0.5;

new DateInterval('PT5M0.5S'); // will throw an Exception

Duration representations

String representation

Deprecated since version 4.5. You should use Duration::format instead.

public Duration::__toString(void): string

Returns the string representation of a Duration object using ISO8601 time interval representation.

$duration = new Duration('PT5M0.5S');
echo $duration; // 'PT5M0.5S'

As per the specification the smallest value (ie the second) can accept a decimal fraction.

Duration mutation method

Adjusting duration according to a datepoint

Since version 4.6

Replaces and deprecates the withoutCarryOver method introduced in version 4.5.

public Duration::adjustedTo($reference_date): self

Returns a new instance with recalculate duration according to the given datepoint. If the recalculate interval does not change the current object then it is returned as is, otherwise a new object is returned.

The reference datepoint can be any valid vaue accepted by the Datepoint::create named constructor.

$duration = Duration::create('29 days');
echo $duration; // 'P29D'
echo $duration->adjustedTo('2019-02-01'); // 'P1M1D' using a non leap year
echo $duration->adjustedTo('2020-02-01'); // 'P1M'   using a leap year

The returned object depends on the date time and timezone or the $reference_date