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

Collection

The League\Period\Collection is an ordered map that can also be used as a list of Interval objects.
This class is heavily inspired by Doctrine\Common\Collections\Collection but also feature specific methods to deal with collection of time range objects.

<?php

use League\Period\Collection;
use League\Period\Period;

$collection = new Sequence([
    'sports' => Period::createFromDuration('2018-05-12 13:30:00', '+1 HOUR'),
    'lunch' => Period::createFromHour('2018-05-12 12:00:00'),
]);
$collection['meeting'] = Period::createFromDuration('2018-05-12 14:00:00', '+2 HOURS');

$intersection = $collection->getIntersections();

$filterCollection = $collection->filter(function (Interval $period) use ($intersection) {
    foreach ($intersection as $interPeriod) {
        if ($interPeriod->intersects($period)) {
            return true;
        }
    }

    return false;
});

$filterCollection->contains($collection['sports']);  //true
$filterCollection->contains($collection['meeting']); //true
$filterCollection->contains($collection['lunch']);   //false
$filterCollection['meeting']->equalsTo($collection->get('meeting')); //true

Collection::getInterval

Returns a Period object which represents the smallest time range containing all the Interval objects of the collection. If the collection is empty this methods returns null.

$retval = $collection->getInterval();
//$retval is a Interval or null

Collection::getGaps

Returns a Collection instance of all the gaps present in the current collection.

$retval = $collection->getGaps();
//$retval is a Collection instance containing all the gaps from $collection

Collection::getIntersections

Returns a Collection instance of all the intersections present in the current collection.

$retval = $collection->getIntersections();
//$retval is a Collection instance containing all the intersection from $collection

Ordered map and list methods

The class implements the following PHP interfaces:

In addition theses methods are also available:

Collection::add

Append a Interval object to the current Collection.

$collection->add(Period::createFromDay('2018-02-03'));

Collection::contains

Tells whether the given Interval object is present in the current Collection.

$collection = new Sequence([Period::createFromDay('2018-02-03')]);
$retval = $collection->contains(Period::createFromDay('2018-02-03')); // true

Notice: comparison is done using Interval::equalsTo method

Collection::containsKey

Tells whether a Interval object present in the current Collection is attached using the $index key.

$collection = new Sequence(['first' => Period::createFromDay('2018-02-03')]);
$retval = $collection->containsKey('first'); // true

Notice: comparison is done using Interval::equalsTo method

Collection::clear

Remove all the Interval objects present in the current Collection.

$collection->clear();

Collection::filter

Filter the current Collection using a predicate function. If the predicate function returns true, the Interval and its related index are added in the returned Collection instance.

$collection = new Sequence([
    'sports' => Period::createFromDuration('2018-05-12 13:30:00', '+1 HOUR'),
    'lunch' => Period::createFromHour('2018-05-12 12:00:00'),
    'meeting' => Period::createFromDuration('2018-05-12 14:00:00', '+2 HOURS'),
]);

$filterCollection = $collection->filter(function (Interval $period) {
    return $period->getTimestampInterval() > 60 * 60;
}); // [Period::createFromDuration('2018-05-12 14:00:00', '+2 HOURS')]

Notice: the Collection::filter method uses the same arguments in the same order as array_filter.

Collection::get

Returns the Interval at the specified $indexin the current Collection. If not object is found or the key is invalid, null is returned.

$collection = new Sequence();
$collection['foo'] = Period::createFromDuration('2018-05-12 13:30:00', '+1 HOUR');
$retval = $collection->get('foo'); // Interval
$retval2 = $collection->get('bar'); // null
//$retval is a Interval object or ǹull

Collection::getKeys

Returns all the indexes/keys present in the current Collection.

$collection = new Sequence();
$collection['foo'] = Period::createFromDuration('2018-05-12 13:30:00', '+1 HOUR');
$retval = $collection->getKeys(); // ['foo']

Collection::getValues

Returns all Interval objects present in the current Collection.

$collection = new Sequence();
$collection['foo'] = Period::createFromDuration('2018-05-12 13:30:00', '+1 HOUR');
$retval = $collection->getValues(); // [Interval]

Collection::first

Returns the first Interval object present in the current Collection or null if the collection is empty.

$collection = new Sequence();
$collection['foo'] = Period::createFromDuration('2018-05-12 13:30:00', '+1 HOUR');
$retval = $collection->first(); // Interval or null if Collection is empty

Collection::last

Returns the last Interval object present in the current Collection or null if the collection is empty.

$collection = new Sequence();
$collection['foo'] = Period::createFromDuration('2018-05-12 13:30:00', '+1 HOUR');
$retval = $collection->last();  // Interval or null if Collection is empty

Collection::indexOf

Returns the index attached to the submitted Interval object present in the current Collection or false the Interval object is not found.

$collection = new Sequence();
$collection['foo'] = Period::createFromDuration('2018-05-03', '+1 DAY');
$retval = $collection->indexOf(Period::createFromDay('2018-05-03')); // 'foo'

Notice: comparison is done using Interval::equalsTo method

Collection::map

Apply the given function to each Interval in the collection and returns a new Collection instance containing the modified Interval objects. Indexes are preserved.

$collection = new Sequence();
$collection['foo'] = Period::createFromDuration('2018-05-03', '+1 DAY');
$retval = $collection->map(function (Interval $period) {
    return $period->endingOn($period->getEndDate()->add(new DateInterval('P1D')));
});
$collection['foo']->getEndDate()->format('Y-m-d'); // 2018-05-4
$retval['foo']->getEndDate()->format('Y-m-d');     // 2018-05-5

Collection::partition

Partitions this Collection instance in two Collection instances according to a predicate. Keys are preserved in the resulting collections. The first instance contains all the Interval objects and their related index which verify the predicate. The second instance contains the remaining objects and their indexes.

$collection = new Sequence([
    'sports' => Period::createFromDuration('2018-05-12 13:30:00', '+1 HOUR'),
    'lunch' => Period::createFromHour('2018-05-12 12:00:00'),
    'meeting' => Period::createFromDuration('2018-05-12 14:00:00', '+2 HOURS'),
]);

$retval = $collection->partition(function (Interval $period, string $index) {
    return false !== strpos($index, 'n');
});
// [
// new Sequence([
//   'lunch' => Period::createFromHour('2018-05-12 12:00:00'),
//   'meeting' => Period::createFromDuration('2018-05-12 14:00:00', '+2 HOURS'),
//  ]),
//  new Sequence(['sports' => Period::createFromDuration('2018-05-12 13:30:00', '+1 HOUR')])
//]

Notice: the predicate first argument is the Interval value and its second optional argument is its index.

Collection::remove

Removes the Interval object from the Collection. If not object was removed false is returned otherwise true is returned.

$collection = new Sequence();
$collection['foo'] = Period::createFromMonth('2018-03-01');
$month = new Period('2018-03-01', '2018-04-01');
$retval = $collection->remove($month); // return true
$retval = $collection->remove(Period::createFromDay('2018-03-01')); //return false

Notice: comparison is done using Interval::equalsTo method

Collection::removeIndex

Removes the Interval object at the specified index from the Collection. If not object was found null is returned otherwise the remove the Interval object is returned.

$collection = new Sequence();
$collection['foo'] = Period::createFromMonth('2018-03-01');
$month = new Period('2018-03-01', '2018-04-01');
$retval = $collection->removeIndex('foo'); // return Period::createFromMonth('2018-03-01');
$retval = $collection->removeIndex('bar'); // return null

Collection::set

Sets a Interval object in the collection at the specified key/index.

$collection = new Sequence();
$retval = $collection->set('foo', Period::createFromWeek(2018, 21));

Collection::slice

Extracts a slice of $length Interval objects starting at position $offset from the Collection.

Calling this method will only return the selected slice and NOT change the elements contained in the collection slice is called on.

$collection = new Sequence([
    'sports' => Period::createFromDuration('2018-05-12 13:30:00', '+1 HOUR'),
    'lunch' => Period::createFromHour('2018-05-12 12:00:00'),
    'meeting' => Period::createFromDuration('2018-05-12 14:00:00', '+2 HOURS'),
]);
$retval = $collection->slice(0, 2);
$retval['meeting']; //returns null

Notice: the Collection::slice method uses the same arguments in the same order as array_slice

Collection::sort

Sorts the Collection with a user defined comparison function while maintaining the index assocation.

$collection = new Sequence([
    'sports' => Period::createFromDuration('2018-05-12 13:30:00', '+1 HOUR'),
    'lunch' => Period::createFromHour('2018-05-12 12:00:00'),
    'meeting' => Period::createFromDuration('2018-05-12 14:00:00', '+2 HOURS'),
]);
$collection->first()->equalsTo($collection['sports']);
$collection->las()->equalsTo($collection['meeting']);
$collection->sort(function (Interval $period1, Interval $period2) {
    return $period2->compareDuration($period1);
});
$collection->first()->equalsTo($collection['lunch']);
$collection->las()->equalsTo($collection['meeting']);

Notice: the Collection::sort method uses the same arguments as uasort.