README

An implementation of the datetime period type for working with temporal intervals. The library includes the full set of relations on intervals defined by Allen's Interval Algebra. For further information see the "Usage" and "How it works" paragraphs.

Requirements
Installation
Usage
How it works
Tests
Changelog
Todo
Licence

Requirements

PHP 7.1+

Installation

$ composer require pwm/datetime-period

Usage

Creation:

$start = new DateTimeImmutable('2010-10-10T10:10:10+00:00');
$end = new DateTimeImmutable('2011-11-11T11:11:11+00:00');
$period = new DateTimePeriod($start, $end);

// Start and end instants (see the definition of instant under "How it works")
$start = $period->getStart(); // DateTimeImmutable('2010-10-10T10:10:10+00:00')
$end = $period->getEnd(); // DateTimeImmutable('2011-11-11T11:11:11+00:00')

Restrictions:

// Throws TimeZoneMismatch exception
new DateTimePeriod(
    new DateTimeImmutable('2017-10-10T10:10:10+02:00'),
    new DateTimeImmutable('2017-10-10T10:10:10-05:00')
);

// Throws NegativeDateTimePeriod exception
new DateTimePeriod(
    new DateTimeImmutable('+1 day'),
    new DateTimeImmutable('-1 day')
);

The full set of relations between 2 periods:

$a = new DateTimePeriod(new DateTimeImmutable('...'), new DateTimeImmutable('...'));
$b = new DateTimePeriod(new DateTimeImmutable('...'), new DateTimeImmutable('...'));

// |--a--|
//          |--b--|
$a->precedes($b);

// |--a--|
//       |--b--|
$a->meets($b);

// |--a--|
//    |--b--|
$a->overlaps($b);

// |----a----|
//     |--b--|
$a->finishedBy($b);

// |----a----|
//   |--b--|
$a->contains($b);

// |--a--|
// |----b----|
$a->starts($b);

// |--a--|
// |--b--|
$a->equals($b);

//  |----a----|
//  |--b--|
$a->startedBy($b);

//   |--a--|
// |----b----|
$a->during($b);

//     |--a--|
// |----b----|
$a->finishes($b);

//    |--a--|
// |--b--|
$a->overlappedBy($b);

//       |--a--|
// |--b--|
$a->metBy($b);

//          |--a--|
// |--b--|
$a->precededBy($b);

Extensibility:

The DateTimePeriod object itself is immutable, meaning that once created you can't change the state of the object, ie. the values of its properties. However the properties have been defined as protected so that you can subclass the type in your project if the need arises.

Working with different granularities:

The 2 periods below meet on a timeline with hour granularity but does not meet on a more fine-grained timeline with minute granularity.

$aStart = '2017-01-01T12:12:09.829462+00:00';
$aEnd   = '2017-01-01T14:23:34.534678+00:00';
$bStart = '2017-01-01T14:41:57.657388+00:00';
$bEnd   = '2017-01-01T16:19:03.412832+00:00';

$hourGranule = 'Y-m-d\TH';
$a = new DateTimePeriod(
    DateTimeImmutable::createFromFormat($hourGranule, (new DateTimeImmutable($aStart))->format($hourGranule)),
    DateTimeImmutable::createFromFormat($hourGranule, (new DateTimeImmutable($aEnd))->format($hourGranule))
);
$b = new DateTimePeriod(
    DateTimeImmutable::createFromFormat($hourGranule, (new DateTimeImmutable($bStart))->format($hourGranule)),
    DateTimeImmutable::createFromFormat($hourGranule, (new DateTimeImmutable($bEnd))->format($hourGranule))
);
assert($a->meets($b) === true); // a meets b by the hour granule

$minuteGranule = 'Y-m-d\TH:i';
$a = new DateTimePeriod(
    DateTimeImmutable::createFromFormat($minuteGranule, (new DateTimeImmutable($aStart))->format($minuteGranule)),
    DateTimeImmutable::createFromFormat($minuteGranule, (new DateTimeImmutable($aEnd))->format($minuteGranule))
);

$b = new DateTimePeriod(
    DateTimeImmutable::createFromFormat($minuteGranule, (new DateTimeImmutable($bStart))->format($minuteGranule)),
    DateTimeImmutable::createFromFormat($minuteGranule, (new DateTimeImmutable($bEnd))->format($minuteGranule))
);
assert($a->meets($b) === false); // a does not meet b by the minute granule

Miscellaneous:

This is a list of small helper methods that can save you time when you need their specific functionality.

Get the number of days in a period:

$start = new DateTimeImmutable('2016-01-01T11:11:11+00:00');
$end = new DateTimeImmutable('2018-01-01T11:11:11+00:00');
$period = new DateTimePeriod($start, $end);
assert(366 + 365 === $period->getNumberOfDays()); // 2016 was a leap year

How it works

In order to be able to talk about periods first let's agree on the following definitions:

Definitions

1. Instant

An anchor, ie. discrete point, on the timeline. The most basic temporal type. A "true" time instant is theoretical like a point on a continuous geometrical line. A representation of an instant, however, always has a duration, called a granule. We can thus represent the same instant using various discreet timelines of different granularities. Eg. "2017-10-10" and "2017-10-10 10:10:10" could represent the same instant.

2. Interval

An unanchored, directed portion of the timeline. Unanchored means it has no absolute relation to the timeline. Examples are "2 weeks" or "1 day, 2 hours and 3 minutes". Directed means it is perfectly valid to say "-3 days".

3. Period

An anchored interval on the timeline. There are several possible representations, the most common being a pair of ordered instants of identical granularity. Depending on the representation the interval of a period can be open or closed on both its start and end. A common way is to use a closed-open interval, ie. [start, end), which helps simplifying calculations. Eg. the period ["2017-10-10", "2017-11-11") includes the instant "2017-10-10" but excludes the instant "2017-11-11".

We arrived to the definition of a period. Now on to...

Relations

Defining relations on periods is somewhat complex as there is no total order. In 1983 James F. Allen wrote a paper in which he defined 13 jointly exhaustive and pairwise disjoint binary relations on intervals, meaning that any 2 intervals are related exactly one way. You can see each of the 13 relations above, in the "Usage" section. These relations and the operations on them form what is referred to as Allen's interval algebra.

Complexities

Dealing with calendrical time is difficult with many peculiarities. This, in turn, means that dealing with derivative entities, like DateTimePeriod is complex as well.

Here is an example involving timezones:

If you try to create a one year DateTimePeriod starting from 2018-03-26T08:00:00 and ending at 2019-03-26T08:00:00 for the timezone Europe/London it would fail with a UTCOffsetMismatch exception. This is because for the start instant the timezone Europe/London equals to BST (which equals to UTC+01:00) while for the end instant Europe/London equals to GMT (which equals to UTC+00:00). This is because daylight saving time happens on different days in different years.

If you create the above period using UTC offsets, ie. from 2018-03-26T08:00:00+01:00 to 2019-03-26T08:00:00+01:00 that would not throw a UTCOffsetMismatch, however the end instant will not be a valid Europe/London datetime so you would have to calculate the correct time for Europe/London from your UTC+01:00 offset.

The supplied DateTimePeriod::getUtcOffset() function can help ease this problem by mapping your current timezone to its UTC offset.

Tests

$ vendor/bin/phpunit
$ composer phpcs
$ composer phpstan
$ composer infection

Changelog

Click here

Todo

Work out a more user friendly solution for the UTC offset / timezone problem.

Licence

MIT

pwm / datetime-period

Maintainers

Details