This is the documentation for version 4.0 which will be supported until TBD. Please consider upgrading your code to the latest stable version

A Period Container

The Sequence class is design to ease gathering information about multiple Period instance.

Period detection

Because Period is a value object, comparison between two instances is done using the Period::equals method instead of == or ===.

Sequence::indexOf

Returns the first offset of the a Period object who’s equals to the submitted instance.

$sequence = new Sequence(new Period('2018-01-01', '2018-01-31'));
$sequence->indexOf(new Period('2018-03-01', '2018-03-31')); // 0
$sequence->indexOf(Datepoint::create('2012-06-03')->getDay()); // false

Sequence::contains

public function Sequence::contains(Period $interval, Period ...$intervals);

Tells whether the sequence contains all the submitted intervals.

$sequence = new Sequence(new Period('2018-01-01', '2018-01-31'));
$sequence->contains(
    new Period('2018-03-01', '2018-03-31'),
    new Period('2018-01-20', '2018-03-10')
); // false

Sequence information

Sequence boundaries

Sequence::boundaries since version 4.4.

Sequence::getBoundaries is deprecated and will be remove in the next major release.

Returns the sequence boundaries as a Period instance. If the sequence is empty null is returned.

$sequence = new Sequence(
    new Period('2018-01-01', '2018-01-31'),
    new Period('2018-02-10', '2018-02-20'),
    new Period('2018-03-01', '2018-03-31'),
    new Period('2018-01-20', '2018-03-10')
);
$sequence->boundaries()->format('Y-m-d'); // [2018-01-01, 2018-03-31)
(new Sequence())->boundaries(); // null

Sequence gaps

Sequence::gaps since version 4.4.

Sequence::getGaps is deprecated and will be remove in the next major release.

Returns the gaps inside the instance. The method returns a new Sequence object containing the founded gaps expressed as Period objects.

$sequence = new Sequence(
    new Period('2018-01-01', '2018-01-31'),
    new Period('2017-01-01', '2017-01-31'),
    new Period('2020-01-01', '2020-01-31')
);
$gaps = $sequence->gaps(); // a new Sequence object
count($gaps); // 2

Sequence intersections

Sequence::intersections since version 4.4.

Sequence::getIntersections is deprecated and will be remove in the next major release.

Returns the intersections inside the instance. The method returns a new Sequence object containing the founded intersections expressed as Period objects.

$sequence = new Sequence(
    new Period('2018-01-01', '2018-01-31'),
    new Period('2017-01-01', '2017-01-31'),
    new Period('2020-01-01', '2020-01-31')
);
$intersections = $sequence->intersections(); // a new Sequence object
$intersections->isEmpty(); // true

Sequence unions

Since version 4.4

Returns the unions inside the instance. The method returns a new Sequence object containing the calculated unions expressed as Period objects.

$sequence = new Sequence(
    new Period('2018-01-01', '2018-01-31'),
    new Period('2017-01-01', '2017-01-31'),
    new Period('2018-01-15', '2018-02-15')
);
$unions = $sequence->unions(); // a new Sequence object
count($unions); // returns 2

Sequence total timestamp interval

Since version 4.7

Returns the sum of all instances durations as expressed in seconds.

$sequence = new Sequence(
    Period::fromMonth(2017, 1),
    Period::fromMonth(2018, 1)
);
$timestamp = $sequence->getTotalTimestampInterval(); // a float

The return value will always be lesser or equals to the result of Sequence::boundaries()->getTimestampInterval().

Container manipulations

Sequence::subtract

Sequence::substract introduced in version 4.7

typo fixed to Sequence::subtract in version 4.9

Sequence::substract is deprecated and will be remove in the next major release.

Sequence::subtract(Sequence $sequence): Sequence

This method enables subtracting a Sequence instance from another one. It internally use Period::subtract and as such is not commutative.

warning: This method is not optimized for subtracting two large collection of Sequence objects.

The following diagram gives you an overview of how the method works:

Examples

$presence = new Sequence(
    new Period('2000-01-01', '2000-01-10'),
    new Period('2000-01-12', '2000-01-20')
);

$absence = new Sequence(
    new Period('2000-01-08', '2000-01-10'),
    new Period('2000-01-12', '2000-01-15')
);

$diff = $presence->subtract($absence);
$diff[0]->format('Y-m-d'); //[2000-01-01, 2000-01-08)
$diff[1]->format('Y-m-d'); //[2000-01-15, 2000-01-20)

$diff = $absence->subtract($presence);
$diff->isEmpty(); // true