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

Instantiation

To instantiate a Period object you can rely on its constructor or on several helper functions describe below.

datepoint and duration conversions are done internally using the League\Period\Datepoint and the League\Period\Duration classes.

The constructor

public Period::__construct(
    mixed $startDate,
    mixed $endDate,
    string $boundaryType = self::INCLUDE_START_EXCLUDE_END
)

Since version 4.4 the $boundaryType argument is added.

Parameters

Both $startDate and $endDate parameters are datepoints. $endDate must be greater or equal to $startDate or the instantiation will throw a Period\Exception.

The $boundaryType can only take one of the following values:

To ease remembering those values the following constants are introduced:

By default and to avoid BC break the $boundaryType is Period::INCLUDE_START_EXCLUDE_END when not explicitly provided.

Example

use League\Period\Period;

$period1 = new Period('2012-04-01 08:30:25', '2013-09-04 12:35:21', '()');
$period2 = new Period('2012-04-01 08:30:25', new DateTime('2013-09-04 12:35:21'), Period::EXCLUDE_ALL);

$period1->equals($period2); // true

Named constructors

Since version 4.2

Apart from its constructor, to ease the class instantiation you can rely on many built in named constructors to return a new Period object.

Named constructors accepting a DatePeriod object

function Period::fromDatePeriod(
    DatePeriod $datePeriod,
    string $boundaryType = self::INCLUDE_START_EXCLUDE_END
): self

Parameter

Since version 4.4 the $boundaryType argument is added.

Example

$daterange = new DatePeriod(
    new DateTime('2012-08-01'),
    new DateInterval('PT1H'),
    new DateTime('2012-08-31')
);
$interval = Period::fromDatePeriod($daterange);
$interval->getStartDate() == $daterange->getStartDate();
$interval->getEndDate() == $daterange->getEndDate();

If the submitted DatePeriod instance does not have a ending datepoint, It will trigger a TypeError error. This is possible if the DatePeriod instance was created using recurrences only

$daterange = new DatePeriod('R4/2012-07-01T00:00:00Z/P7D');
$interval = Period::fromDatePeriod($daterange);
//throws a TypeError error because $daterange->getEndDate() returns null

Named constructors accepting a datepoint and/or a duration

public static Period::after(mixed $datepoint, mixed $duration, string $boundaryType = self::INCLUDE_START_EXCLUDE_END): Period
public static Period::before(mixed $datepoint, mixed $duration, string $boundaryType = self::INCLUDE_START_EXCLUDE_END): Period
public static Period::around(mixed $datepoint, mixed $duration, string $boundaryType = self::INCLUDE_START_EXCLUDE_END): Period

Parameters

Since version 4.4 the $boundaryType argument is added.

Examples

Using Period::after, Period::around, Period::before:

$date = Datepoint::create('2012-04-01 08:30:25');
$duration = Duration::create('1 DAY');
$half_duration = Duration::create('12 HOURS');

$interval_after = Period::after($date, $duration);
$interval_before = Period::before($date->add($duration), $duration);
$interval_after->equals($interval_before); //returns true
$interval_around = Period::around($date->add($half_duration), $half_duration);
$interval_around->equals($interval_before); //returns true

Named constructors accepting a list of integer arguments

The week index follows the ISO week date system. This means that the first week may be included in the previous year, conversely the last week may be included in the next year.

public static Period::fromDay(int $year, int $month = 1, int $day = 1, string $boundaryType = self::INCLUDE_START_EXCLUDE_END): Period
public static Period::fromIsoWeek(int $year, int $week = 1, string $boundaryType = self::INCLUDE_START_EXCLUDE_END): Period
public static Period::fromMonth(int $year, int $month = 1, string $boundaryType = self::INCLUDE_START_EXCLUDE_END): Period
public static Period::fromQuarter(int $year, int $quarter = 1, string $boundaryType = self::INCLUDE_START_EXCLUDE_END): Period
public static Period::fromSemester(int $year, int $semester = 1, string $boundaryType = self::INCLUDE_START_EXCLUDE_END): Period
public static Period::fromYear(int $year, string $boundaryType = self::INCLUDE_START_EXCLUDE_END): Period
public static Period::fromIsoYear(int $year, string $boundaryType = self::INCLUDE_START_EXCLUDE_END): Period

Parameters

The datepoints will be created following PHP DateTimeImmutable::setDate, DateTimeImmutable::setISODate and DateTimeImmutable::setTime rules
which means that overflow is possible and acceptable.

The following named constructors always returns a Period instance with the following boundary type Period::INCLUDE_START_EXCLUDE_END.

Since version 4.9 the $boundaryType argument is added.

Examples

$day = Period::fromDay(2012);
$daybis = Period::fromDay(2012, 1);
$day->equals($daybis); //return true;
$day->getStartDate()->format('Y-m-d H:i:s'); //return 2012-01-01 00:00:00

Helper functions

The following functions are deprecated since version 4.2 and will be remove in the next major release. Please consider using the named constructors instead.

Apart from its constructor, to ease the class instantiation you can rely on many built in helper functions to return a new Period object. All helper functions are declared under the League\Period namespace.

use League\Period;
use function League\Period\interval_after;

$period = Period\interval_after('YESTERDAY', '2 MINUTE');
$alt_period = interval_after('YESTERDAY', 180);

$alt_period->equals($period);

Helper functions accepting a list of integer arguments or a datepoint

Using a list of integer arguments

The time is truncated so that the duration always starts at midnight according to the date timezone.

The week index follows the ISO week date system. This means that the first week may be included in the previous year, conversely the last week may be included in the next year.

function League\Period\instant(int $year, int $month = 1, int $day = 1, int $hour = 0, int $minute = 0, int $second = 0, int $microsecond = 0): Period
function League\Period\second(int $year, int $month = 1, int $day = 1, int $hour = 0, int $minute = 0, int $second = 0): Period
function League\Period\minute(int $year, int $month = 1, int $day = 1, int $hour = 0, int $minute = 0): Period
function League\Period\hour(int $year, int $month = 1, int $day = 1, int $hour = 0): Period
function League\Period\day(int $year, int $month = 1, int $day = 1): Period
function League\Period\month(int $year, int $month = 1): Period
function League\Period\year(int $year): Period
function League\Period\quarter(int $year, int $quarter = 1): Period
function League\Period\semester(int $year, int $semester = 1): Period
function League\Period\iso_week(int $year, int $week = 1): Period
function League\Period\iso_year(int $year): Period

Using a datepoint

function League\Period\instant(mixed $datepoint): Period
function League\Period\second(mixed $datepoint): Period
function League\Period\minute(mixed $datepoint): Period
function League\Period\hour(mixed $datepoint): Period
function League\Period\day(mixed $datepoint): Period
function League\Period\month(mixed $datepoint): Period
function League\Period\year(mixed $datepoint): Period
function League\Period\quarter(mixed $datepoint): Period
function League\Period\semester(mixed $datepoint): Period
function League\Period\iso_week(mixed $datepoint): Period
function League\Period\iso_year(mixed $datepoint): Period

Examples

use League\Period;

$instant = Period\instant('2012-04-01');
$alt_i = Period\instant(2012, 4, 1);
$alt_i->equals($instant); //return true;

$second = Period\second('2012-04-01 08:30:25');
$alt_s  = Period\second(2012, 4, 1, 8, 30, 25);
$alt_s->equals($second); //return true;

$minute = Period\minute('2012-04-01 08:30:25');
$alt_m  = Period\minute(2012, 4, 1, 8, 30, 48);
$alt_m->equals($minute); //return true;

$hour = Period\hour('2012-04-01 08:30:25');
$alt_h = Period\hour(2012, 4, 1, 8);
$alt_h->equals($hour); //return true;

$day = Period\day(2012, 4, 1);
$day_string = Period\day('2012-04-01 08:30:25');
$alt_d = Period\day('2012-04-01');
$alt_d->equals($day); //return true;
$day_string->equals($day); //return true;

$week = Period\iso_week(2013, 23);
$alt_w = Period\iso_week('2013-06-05');
$alt_w->equals($week); //return true;
//this period represents the 23rd week of 2013

$month = Period\month(2013, 7);
$alt_m = Period\month('2013-07-31');
$alt_m->equals($month); //return true;
//this period represents the month of July 2013

$quarter = Period\quarter(2013, 2);
$alt_q = Period\quarter('2013-05-15');
$alt_q->equals($quarter); //return true;
//this period represents the second quarter of 2013

$semester = Period\semester(2013, 2);
$alt_s = Period\semester('2013-03-15');
$alt_s->equals($semester); //return true;
//this period represents the second semester of 2013

$year = Period\year(2013);
$alt_y = Period\year('2013-05-15');
$alt_y->equals($year); //return true;
//this period represents a the year 2013 time range

$iso_year = Period\iso_year(2013);
$alt_iy = Period\iso_year('2013-05-15');
$alt_iy->equals($iso_year); //return true;
//this period represents a the iso year 2013 time range

Create a new instance from a datepoint and a duration

function League\Period\interval_after(mixed $datepoint, mixed $duration): Period
function League\Period\interval_before(mixed $datepoint, mixed $duration): Period
function League\Period\interval_around(mixed $datepoint, mixed $duration): Period

Parameters

Example

$date = datepoint('2012-04-01 08:30:25');
$duration = duration('1 DAY');
$half_duration = duration('12 HOURS');

$interval_after = interval_after($date, $duration);
$interval_before = interval_before($date->add($duration), $duration);
$interval_after->equals($interval_before); //returns true
$interval_around = interval_around($date->add($half_duration), $half_duration);
$interval_around->equals($interval_before); //returns true

Create a new instance from a DatePeriod object

function League\Period\interval_from_dateperiod(DatePeriod $datePeriod): Period

Parameter

Example

$daterange = new DatePeriod(
    new DateTime('2012-08-01'),
    new DateInterval('PT1H'),
    new DateTime('2012-08-31')
);
$interval = interval_from_dateperiod($daterange);
$interval->getStartDate() == $daterange->getStartDate();
$interval->getEndDate() == $daterange->getEndDate();

If the submitted DatePeriod instance does not have a ending datepoint, It will trigger a TypeError error. This is possible if the DatePeriod instance was created using recurrences only

$daterange = new DatePeriod('R4/2012-07-01T00:00:00Z/P7D');
$interval = interval_from_dateperiod($daterange);
//throws a TypeError error because $daterange->getEndDate() returns null