The League of Extraordinary Packages

Our Packages:

Presented by The League of Extraordinary Packages


Time range API for PHP

$ composer require league/period


Current Stable


  • Requires: PHP >= 5.5.9
  • Latest: 3.3.0 - 2016-09-19
  • Supported Until: TBD

Full Documentation



  • Requires: PHP >= 5.3.0
  • Latest: 2.5.1 - 2015-03-09
  • Supported Until: 2015-09-09

Once a new major version is released, the previous stable release remains supported for six more months through patches and security fixes.


`Period` is PHP's Time Range class. It is based on [Resolving Feature Envy in the Domain]( by Mathias Verraes and extends the concept to cover all basic operations regarding time ranges.

  1. Treats Time Range as immutable value objects

  2. Exposes many named constructors to ease time range creation

  3. Covers all basic manipulations related to time range

  4. Framework-agnostic


Multiple named constructors

To help you start working with Period objects


use League\Period\Period;

$period = new Period(new DateTime('2014-10-15 08:35:26'), '2014-10-15 08:53:12');
Period::createFromSemester(2014, 1);
Period::createFromQuarter(2014, 1);
Period::createFromMonth(2014, 1);
Period::createFromWeek(2014, 1);
Period::createFromDuration('2014-01-01 08:00:25', new DateInterval('PT1H'));
Period::createFromDurationBeforeEnd('2014-01-01 08:00:25', 3600);

Accessing time range properties

Once instantiated, you can access Period datepoints and durations easily:


use League\Period\Period;

$period = Period::createFromDuration('2014-10-03 08:12:37', 3600);
$start = $period->getStartDate();
$end = $period->getEndDate();
$duration = $period->getDateInterval();
$duration2 = $period->getTimestampInterval();
echo $period;

Different ways to iterate over the time range

You can return selected datepoints inside the Period time range


use League\Period\Period;

$period = Period::createFromMonth(2014, 10);
foreach ($period->getDatePeriod('1 DAY') as $datepoint) {
    echo $datepoint->format('Y-m-d');

or split the given time range into smaller Period objects


use League\Period\Period;

$period = Period::createFromMonth(2014, 10);
foreach ($period->split('1 DAY') as $period) {
    echo $period;

Comparing different time ranges simplified

You can compare time ranges based on their duration and/or their datepoints.


use League\Period\Period;

$period = Period::createFromDuration('2014-01-01', '1 WEEK');
$altPeriod = Period::createFromWeek(2014, 3);
$period->sameDurationAs($altPeriod); //will return true because the duration are equals
$period->sameValueAs($altPeriod); //will return false because the datepoints differ

Modifying time ranges

Period is an immutable value object. Any changes to the object returns a new object.


use League\Period\Period;

$period = Period::createFromDuration('2014-01-01', '1 WEEK');
$altPeriod = $period->endingOn('2014-02-03');
$period->contains($altPeriod); //return false;
$altPeriod->durationGreaterThan($period); //return true;


Period was created by Ignace Nyamagana Butera. Find him on Twitter at @nyamsprod.