The League of Extraordinary Packages

Our Packages:

Presented by The League of Extraordinary Packages

Getting Started


Upgrading Guide

This is the documentation for the upcoming version 4.0. This is a work in progress


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

The default constructor



public Period::__construct(mixed $startDate, mixed $endDate)


Both $startDate and $endDate parameters represent the period datepoints.

$endDate must be greater or equal to $startDate or the instantiation will throw a Period\Exception.



use League\Period\Period;

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

Create an instance from a DatePeriod object.



public Period::fromDatePeriod(DatePeriod $datePeriod): Period


The $datePeriod is a DatePeriod object.


use League\Period\Period;

$begin = new DateTime('2012-08-01');
$end = new DateTime('2012-08-31');
$interval = new DateInterval('PT1H');

$period = Period::fromDatePeriod(new DatePeriod($begin, $interval, $end));

If the submitted `DatePeriod` instance does not have a ending datepoint, It will trigger and Period\Exception.

Helper functions

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);


Helper functions accepting only a datepoint


function instant(mixed $datepoint): Period
function second(mixed $datepoint): Period
function minute(mixed $datepoint): Period
function hour(mixed $datepoint): Period



$instant = instant('2012-04-01 08:30:25.124546');
$instant->getStartDate() === $instant->getEndDate(); //returns true
$instant->getDateInterInterval() == new DateInterval('PT0S'); //returns true

$second = second('2012-04-01 08:30:25.124546');
$alt_s  = second('2012-04-01 08:30:25');
$alt_s->equals($second); //return true;

$minute = minute('2012-04-01 08:30:25');
$alt_m  = minute('2012-04-01 08:30:00');
$alt_m->equals($minute); //return true;

$hour = hour('2012-04-01 08:30:25');
$alt_h = hour('2012-04-01 08:00:00');
$alt_h->equals($hour); //return true;

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.

Values exceeding accepted ranges will trigger Period\Exception


function day(int $year [, int $month = 1 [, int $day = 1]]): Period
function iso_week(int $year [, int $week = 1]): Period
function month(int $year [, int $month = 1]): Period
function quarter(int $year [, int $quarter = 1]): Period
function semester(int $year [, int $semester = 1]): Period
function year(int $year): Period
function iso_year(int $year): Period

Using a datepoint

The starting datepoint is determined using DateTime::__construct parser. Values exceeding ranges will be added to their parent values.

function day(mixed $datepoint): Period
function iso_week(mixed $datepoint): Period
function month(mixed $datepoint): Period
function quarter(mixed $datepoint): Period
function semester(mixed $datepoint): Period
function year(mixed $datepoint): Period
function iso_year(mixed $datepoint): Period


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

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

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

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

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

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

$iso_year = iso_year(2013);
$alt_iy = 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 interval_after(mixed $datepoint, mixed $duration): Period
function interval_before(mixed $datepoint, mixed $duration): Period
function interval_around(mixed $datepoint, mixed $duration): Period



$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