Period

Accessing properties

Getter Period informations

Once you have a instantiated Period object you can access the object datepoints and durations using the following getter methods:

public Period::getStartDate(void): DateTimeImmutable
public Period::getEndDate(void): DateTimeImmutable
public Period::getDateInterval(void): DateInterval
public Period::getTimestampInterval(void): float
$period = new Period('2012-04-01 08:30:25', new DateTime('2013-09-04 12:35:21'));
$period->getStartDate(); //returns DateTimeImmutable('2012-04-01 08:30:25');
$period->getEndDate(); //returns DateTimeImmutable('2013-09-04 12:35:21');
$duration = $period->getDateInterval(); //returns a DateInterval object
$altduration = $period->getTimestampInterval(); //returns the duration in seconds

Iteration over a Period

duration conversion is done internally using the League\Period\duration function

Period::getDatePeriod

public Period::getDatePeriod(mixed $duration, int $option): DatePeriod

Returns a DatePeriod using the Period datepoints with the given $duration.

When iterating over a DatePeriod object returns by the Period::getDatePeriod all the generated datepoints are DateTimeImmutable instances.

Parameters

Examples

use function League\Period\year;

foreach (year(2012)->getDatePeriod('1 MONTH') as $datetime) {
    echo $datetime->format('Y-m-d');
}
//will iterate 12 times
////the first date is 2012-01-01
//the last date is 2012-12-01

Using the $option parameter

$interval = year('2012-06-05');
$datePeriod = $interval->getDatePeriod('1 MONTH', DatePeriod::EXCLUDE_START_DATE);
foreach ($datePeriod as $datetime) {
    echo $datetime->format('Y-m-d');
}
//will iterate 11 times
//the first date is 2012-02-01
//the last date is 2012-12-01

Period::getDatePeriodBackwards

public Period::getDatePeriodBackwards(mixed $duration, int $option): iterable<DateTimeImmutable>

Returns a Generator to allow iteration over the instance datepoints, recurring at regular intervals, backwards starting from the ending datepoint.

Parameters

duration conversion is done internally using the League\Period\duration function

Examples

use function League\Period\year;

foreach (year(2012)->getDatePeriodBackwards('1 MONTH') as $datetime) {
    echo $datetime->format('Y-m-d');
}
//will iterate 12 times
//the first date is 2013-01-01
//the last date is 2012-02-01

Using the $option parameter

$interval = year('2012-06-05');
$datePeriod = $interval->getDatePeriodBackwards('1 MONTH', DatePeriod::EXCLUDE_START_DATE);
foreach ($datePeriod as $datetime) {
    echo $datetime->format('Y-m-d');
}
//will iterate 11 times
//the first date is 2012-12-01
//the last date is 2012-02-01

Period::split

public Period::split(mixed $duration): Generator

This method splits a given Period object in smaller Period objects according to the given $duration starting from the object starting datepoint to its ending datepoint. The result is returned as a Generator object. All returned objects must be contained or abutted to the parent Period object.

duration conversion is done internally using the League\Period\duration function

Example

foreach (year(2012)->split('1 MONTH') as $inner_periods) {
    echo $inner_period; //returns Period object whose interval is 1 MONTH
}
//will iterate 12 times

Period::splitBackwards

public Period::splitBackwards(mixed $duration): Generator

This method splits a given Period object in smaller Period objects according to the given $duration starting from the object ending datepoint to its starting datepoint. The result is returned as a Generator object. All returned objects must be contained or abutted to the parent Period object.

duration conversion is done internally using the League\Period\duration function

Example

date_default_timezone_set('Africa/Kinshasa');

$collection = iterator_to_array(year(2012)->splitBackwards('5 MONTH'));
echo $collection[0]; // 2012-07-31T23:00:00Z/2012-12-31T23:00:00Z (5 months interval)
echo $collection[1]; // 2012-02-29T23:00:00Z/2012-07-31T23:00:00Z (5 months interval)
echo $collection[2]; // 2011-12-31T23:00:00Z/2012-02-29T23:00:00Z (2 months interval)

Period representations

String representation

public Period::__toString(void): string

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

date_default_timezone_set('Africa/Nairobi');

$period = new Period('2014-05-01 00:00:00', '2014-05-08 00:00:00');
echo $period; // '2014-04-30T23:00:00.000000Z/2014-05-07T23:00:00.000000Z'

JSON representation

public Period::jsonSerialize(void): array

Period implements the JsonSerializable interface and is directly usable with PHP json_encode function as shown below:

date_default_timezone_set('Africa/Kinshasa');

$period = new Period('2014-05-01 00:00:00', '2014-05-08 00:00:00');

$res = json_decode(json_encode($period), true);
//  $res will be equivalent to:
// [
//      'startDate' => '2014-04-30T23:00:00.000000Z,
//      'endDate' => '2014-05-07T23:00:00.000000Z',
// ]

This format was chosen to enable better compatibility with Javascript Date representation.

Mathematical representation

public Period::format(string $format): string

You can use the format method to represent a Period object in its mathematical representation as a left closed, right open interval as show below. the $format parameter expects a string which follow date first argument rules.

$interval = new Period('2014-05-01 00:00:00', '2014-05-08 00:00:00');
echo $interval->format('Y-m-d'); // [2014-05-01, 2014-05-08)

This representation can be used, for instance, in a PostreSQL query against a DateRange field.