The League of Extraordinary Packages

Our Packages:

Presented by The League of Extraordinary Packages

Getting Started

The API

Upgrading Guide

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

Instantiation

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

The default constructor

Description

<?php

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

Parameters

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.

Examples

<?php

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.

Description

<?php

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

Parameters

The $datePeriod is a DatePeriod object.

Examples

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

$alt_period->equals($period);

Helper functions accepting only a datepoint

<?php

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

Parameter

Example

$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

<?php

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.

<?php
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

Examples

$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

<?php

function interval_after(mixed $datepoint, mixed $duration): Period
function interval_before(mixed $datepoint, mixed $duration): Period
function 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