Accessing properties
Whenever a duration is expected the following types are supported:
DateIntervalPeriodDuration- a
stringparsable byDateInterval::createFromDateString
Unless explicitly restricted, whenever a datepoint is expected the following types are supported:
DateTimeInterfaceDatePoint- a
stringparsable byDateTimeImmutable::__construct
Period representations
String representation
public Period::toIso8601(): string
Returns the string representation of a Period object using ISO8601 time interval representation.
date_default_timezone_set('Africa/Nairobi');
$period = Period::fromIso80000('Y-m-d H:i:s', '[2014-05-01 00:00:00, 2014-05-08 00:00:00)');
echo $period->toIso8601(); // '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 = Period::fromIso80000('Y-m-d H:i:s', '[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',
// 'startDateIncluded' => true,
// 'endDateIncluded' => false,
// ]
This format was chosen to enable better compatibility with Javascript Date representation.
Mathematical representation
public Period::toIso80000(string $format): string
public Period::toBourbaki(string $format): string
You can use the format method to represent a Period object in its mathematical representation as shown below.
- The
$formatparameter expects a string which follow date first argument rules. - The boundary representation depends on the
Periodboundaries property.
$period = Period::fromIso80000('Y-m-d H:i:s', '[2014-05-01 00:00:00, 2014-05-08 00:00:00)');
echo $period->toIso80000('Y-m-d'); // [2014-05-01, 2014-05-08)
echo $period->toBourbaki('Y-m-d'); // [2014-05-01, 2014-05-08[
This representation can be used, for instance, in a PostgreSQL query against a DateRange field.
Duration representation
You can represent a period as a DateInterval object or as a duration expressed in seconds. Those representation are
bounds independent.
use League\Period\Bounds;
public Period::dateInterval(): DateInterval
public Period::timeDuration(): int
use League\Period\Period;
$period = Period::fromDate('2012-04-01 08:30:25', '2013-09-04 12:35:21');
$period->dateInterval(); // returns a DateInterval object
$period->timeDuration(); // returns the duration in seconds
Period properties
Once you have a instantiated Period object you can access the object datepoints, durations and bounds using the following getter methods:
use League\Period\Bounds;
public readonly DateTimeImmutable Period::startDate
public readonly DateTimeImmutable Period::endDate
public readonly Bounds Period::bounds
use League\Period\Period;
$period = Period::fromDate('2012-04-01 08:30:25', '2013-09-04 12:35:21');
$period->startDate; // returns DateTimeImmutable('2012-04-01 08:30:25');
$period->endDate; // returns DateTimeImmutable('2013-09-04 12:35:21');
$period->bounds; // returns Bounds::IncludeStartExcludeEnd
More information can be extracted from the Bounds enum, please refer to its documentation page.
Iteration over a Period
Iterating over a Period instance can produce two outcomes. A collection of DateTimeImmutable discrete values or one
of smaller Period instances.
Period::rangeForward and Period::rangeBackwards
public Period::rangeForward(Period|Duration|DateInterval|string $timeDelta): DatePeriod
Period::rangeForward returns a DatePeriod instance using the Period datepoints and bounds with the given $timeDelta.
When iterating over the resulting DatePeriod object, all the generated datepoints are DateTimeImmutable instances.
Examples
use League\Period\Period;
foreach (Period::fromYear(2012)->rangeForward('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
The method takes into account the Period bounds to include or not the interval endpoints in the resulting generator.
Period::dateRangeForward
Period::dateRangeForward is deprecated since version 5.2 and will be removed in the next major version. Please use the Period::rangeForward method instead.
use League\Period\InitialDatePresence;
public Period::dateRangeForward(Period|Duration|DateInterval|string $timeDelta, InitialDatePresence $startDatePresence = InitialDatePresence::Included): DatePeriod
Returns a DatePeriod using the Period datepoints with the given $timeDelta.
When iterating over the resulting DatePeriod object, all the generated datepoints are DateTimeImmutable instances.
Parameters
$startDatePresenceCan be set toInitialDatePresence::IncludedorInitialDatePresence::Excludedto exclude the initial date from the set of recurring dates within the period.
Examples
use League\Period\Duration;
use League\Period\Period;
foreach (Period::fromYear(2012)->dateRangeForward('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 $startDatePresence parameter
use League\Period\InitialDatePresence;
use League\Period\Duration;
use League\Period\Period;
$dateRange = Period::fromYear(2012)->dateRangeForward('1 MONTH', InitialDatePresence::Excluded);
foreach ($dateRange 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::rangeBackwards
public Period::rangeBackwards(Period|Duration|DateInterval|string $timeDelta): Generator<DateTimeImmutable>
Period::rangeBackward returns a Generator instance using the Period endpoints and bounds with the given $timeDelta.
When iterating over the resulting DatePeriod object, all the generated datepoints are DateTimeImmutable instances.
Examples
use League\Period\Period;
foreach (Period::fromYear(2012)->rangeBackwards('1 MONTH') as $datetime) {
echo $datetime->format('Y-m-d');
}
// will iterate 12 times
// the first date is 2012-12-01
// the last date is 2012-01-01
Period::dateRangeBackwards
Period::dateRangeBackwards is deprecated since version 5.2 and will be removed in the next major version. Please use the Period::rangeBackwards method instead.
use League\Period\InitialDatePresence;
public Period::dateRangeBackwards(Period|Duration|DateInterval|string $timeDelta, InitialDatePresence $endDatePresence = InitialDatePresence::Included): Generator<DateTimeImmutable>
Returns a Generator to allow iteration over the instance datepoints, recurring at regular intervals, backwards starting from the ending datepoint.
Parameters
$endDatePresenceCan be set toInitialDatePresence::IncludedorInitialDatePresence::Excludedto exclude the initial date from the set of recurring dates within the period.
Examples
foreach (Period::fromYear(2012)->dateRangeBackwards(new DateInterval('P1M')) 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 $endDatePresence parameter
$interval = Period::fromYear('2012-06-05');
$dateRange = $interval->dateRangeBackwards(new DateInterval('P1M'), InitialDatePresence::Excluded);
foreach ($dateRange 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::splitForward
public Period::splitForward(Period|Duration|DateInterval|string $duration): Generator<Period>
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.
- The first returned
Periodwill always share the same starting datepoint with the parent object. - The last returned
Periodwill always share the same ending datepoint with the parent object. - The last returned
Periodwill have a duration equal or lesser than the submitted interval. - If
$intervalis greater than the parentPeriodinterval, the generator will contain a singlePeriodwhose datepoints equals those of the parentPeriod.
Example
foreach (Period::fromYear(2012)->splitForward(new DateInterval('P1M')) as $period) {
echo $period->toIso80000('Y-m-d'); //returns Period object whose interval is 1 MONTH
}
//will iterate 12 times
Period::splitBackwards
public Period::splitBackwards(Period|Duration|DateInterval|string $duration): Generator<Period>
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.
- The first returned
Periodwill always share the same ending datepoint with the parent object. - The last returned
Periodwill always share the same starting datepoint with the parent object. - The last returned
Periodwill have a duration equal or lesser than the submitted interval. - If
$intervalis greater than the parentPeriodinterval, the generator will contain a singlePeriodwhose datepoints equals those of the parentPeriod.
Example
date_default_timezone_set('Africa/Kinshasa');
$collection = iterator_to_array(Period::fromYear(2012)->splitBackwards('5 MONTH'), false);
echo $collection[0]->toIso8601(); // 2012-07-31T23:00:00Z/2012-12-31T23:00:00Z (5 months interval)
echo $collection[1]->toIso8601(); // 2012-02-29T23:00:00Z/2012-07-31T23:00:00Z (5 months interval)
echo $collection[2]->toIso8601(); // 2011-12-31T23:00:00Z/2012-02-29T23:00:00Z (2 months interval)