Logo
PERIOD

This is the documentation for version 4.0 which will be supported until 2022-08-21. 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

  • The $startDate represents the starting datepoint.
  • The $endDate represents the ending datepoint.
  • The $boundaryType represents the interval boundary type.

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:

  • [] : the starting and ending datepoints are included in the interval;
  • () : the starting and ending datepoints are excluded from the interval;
  • (] : the starting datepoint is excluded from and the ending datepoint is included in the interval;
  • [) : the starting datepoint is included in and the ending datepoint is excluded from the interval;

To ease remembering those values the following constants are introduced:

  • Period::INCLUDE_ALL whose value is [];
  • Period::EXCLUDE_ALL whose value is ();
  • Period::EXCLUDE_START_INCLUDE_END whose value is (];
  • Period::INCLUDE_START_EXCLUDE_END whose value is [);

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

  • $datePeriod is a DatePeriod object.
  • $boundaryType, the interval boundary type.

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
  • Period::after returns a Period object which starts at $datepoint
  • Period::before returns a Period object which ends at $datepoint
  • Period::around returns a Period object where the given duration is simultaneously subtracted from and added to the $datepoint.

Parameters

  • $datepoint represents a datepoint.
  • $duration represents a duration.
  • $boundaryType the interval boundary type.

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

  • $year parameter is always required;
  • the $semester, $quarter, $month, $week, $day arguments will default to 1;
  • $boundaryType, the interval boundary type.

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

  • $year must be an int;
  • $semester must be an int default to 1;
  • $quarter must be an int default to 1;
  • $month must be an int default to 1;
  • $week must be an int default to 1;
  • $day must be an int default to 1;
  • $hour must be an int default to 0;
  • $minute must be an int default to 0;
  • $second must be an int default to 0;
  • $microsecond must be an int default to 0;

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

  • $datepoint: The datepoint is truncated so that the duration starts at midnight according to the timezone at the beginning of the given datetime period.
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
  • interval_after returns a Period object which starts at $datepoint
  • interval_before returns a Period object which ends at $datepoint.
  • interval_around returns a Period object where the given duration is simultaneously subtracted from and added to the $datepoint.

Parameters

  • The $datepoint parameter represent a datepoints
  • The $duration represents a duration.

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

  • $datePeriod is a DatePeriod object.

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