This is the documentation for the unsupported version 3.0. Please consider upgrading your code to the latest stable version
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:
<?php
public Period::getStartDate(void): DateTimeImmutable
public Period::getEndDate(void): DateTimeImmutable
public Period::getDateInterval(void): DateInterval
public Period::getTimestampInterval(void): float
BC Break :getStartDate and getEndDate now return a DateTimeImmutable object.
<?php
use League\Period\Period;
$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 interval as expressed in seconds
Iteration over a Period
Period::getDatePeriod
The $option parameter is new to version 3.1.
Description
<?php
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
$durationis a interval$optionCan be set toDatePeriod::EXCLUDE_START_DATEto exclude the start date from the set of recurring dates within the period.
Examples
<?php
use League\Period\Period;
$period = new Period('2012-01-01', '2013-01-01');
foreach ($period->getDatePeriod('1 MONTH') as $datetime) {
echo $datetime->format('F, Y');
}
//will iterate 12 times
Using the $option parameter
<?php
use League\Period\Period;
$period = new Period('2012-01-01', '2013-01-01');
$iterator = $period->getDatePeriod('1 MONTH', DatePeriod::EXCLUDE_START_DATE);
foreach ($iterator as $datetime) {
echo $datetime->format('F, Y');
}
//will iterate 11 times
Period::split
BC Break : In version 3, this method returns an generator instead of an array.
Description
<?php
public Period::split(mixed $duration): Generator
This method splits a given Period object in smaller Period objects according to the given $interval startinf 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
<?php
use League\Period\Period;
$period = Period::createFromYear(2012);
$period_list = $period->split('1 MONTH');
foreach ($period_list as $inner_periods) {
echo $inner_period; //returns the string representation of a Period object
}
//will iterate 12 times
Period::splitBackwards
This method is introduced in version 3.4.0
Description
<?php
public Period::splitBackwards(mixed $duration): Generator
This method splits a given Period object in smaller Period objects according to the given $interval 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
<?php
date_default_timezone_set('Africa/Kinshasa');
use League\Period\Period;
$period = Period::createFromYear(2012);
$period_list = iterator_to_array($period->splitBackwards('5 MONTH'));
echo $period_list[0]; // 2012-07-31T23:00:00Z/2012-12-31T23:00:00Z (5 months interval)
echo $period_list[1]; // 2012-02-29T23:00:00Z/2012-07-31T23:00:00Z (5 months interval)
echo $period_list[2]; // 2011-12-31T23:00:00Z/2012-02-29T23:00:00Z (2 months interval)
Period representations
String representation
<?php
public Period::__toString(void): string
Returns the string representation of a Period object using ISO8601 time interval representation.
<?php
date_default_timezone_set('Africa/Nairobi');
use League\Period\Period;
$period = new Period('2014-05-01 00:00:00', '2014-05-08 00:00:00');
echo $period; // '2014-04-30T21:00:00Z/2014-05-07T21:00:00Z'
Json representation
Because DateTimeImmutable can not be json encoded in HHVM, jsonSerialize returns DateTime objects.
<?php
public Period::jsonSerialize(void): array
Period implements the JsonSerializable interface and is directly usable with PHP json_encode function as shown below:
<?php
date_default_timezone_set('Africa/Kinshasa');
use League\Period\Period;
$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' => [
// 'date' => '2014-05-01 00:00:00',
// 'timezone_type' => 3,
// 'timezone' => 'Africa/Kinshasa',
// ],
// 'endDate' => [
// 'date' => '2014-05-08 00:00:00',
// 'timezone_type' => 3,
// 'timezone' => 'Africa/Kinshasa',
// ],
// ]
microseconds may appear starting with version 5.5.14.