The League of Extraordinary Packages

Our Packages:

Presented by The League of Extraordinary Packages

Period

Time range API for PHP

$ composer require league/period

Releases

Current Stable

league/period:^3.0

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

Full Documentation

Unsupported

league/period:^2.0

  • 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.

Highlights

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

Features

Multiple named constructors

To help you start working with Period objects

<?php

use League\Period\Period;

$period = new Period(new DateTime('2014-10-15 08:35:26'), '2014-10-15 08:53:12');
Period::createFromYear(2014);
Period::createFromSemester(2014, 1);
Period::createFromQuarter(2014, 1);
Period::createFromMonth(2014, 1);
Period::createFromWeek(2014, 1);
Period::createFromDay('NOW');
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:

<?php

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

<?php

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

<?php

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.

<?php

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.

<?php

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;

Questions?

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