Complex period comparisons

This package adds support for comparing multiple dates with each other. You can calculate the overlaps and differences between n-amount of periods, as well as some more basic comparisons between two periods.

Periods can be constructed from any type of DateTime implementation, making this package compatible with custom DateTime implementations like Carbon (see cmixin/enhanced-period to convert directly from and to CarbonPeriod).

Periods are always immutable, there's never the worry about your input dates being changed.

Support us

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.

Installation

You can install the package via composer:

composer require spatie/period

Usage

Creating periods

You're encouraged to create periods using their static constructor:

$period = Period::make('2021-01-01', '2021-01-31');

You can manually construct a period, but you'll need to manually provide its precision and boundaries. Using Period::make, the default precision (Precision::DAY()) and default boundaries (Boundaries::EXCLUDE_NONE()) are used.

Before discussing the API provided by this package, it's important to understand both how precision and boundaries are used.

Precision

Date precision is of utmost importance if you want to reliably compare two periods. The following example:

Given two periods: [2021-01-01, 2021-01-15] and [2021-01-15, 2021-01-31]; do they overlap?

At first glance the answer is "yes": they overlap on 2021-01-15. But what if the first period ends at 2021-01-15 10:00:00, while the second starts at 2021-01-15 15:00:00? Now they don't anymore!

This is why this package requires you to specify a precision with each period. Only periods with the same precision can be compared.

A more in-depth explanation on why precision is so important can be found here. A period's precision can be specified when constructing that period:

Period::make('2021-01-01', '2021-02-01', Precision::DAY());

The default precision is set on days. These are the available precision options:

Precision::YEAR()
Precision::MONTH()
Precision::DAY()
Precision::HOUR()
Precision::MINUTE()
Precision::SECOND()

Boundaries

By default, period comparisons are done with included boundaries. This means that these two periods overlap:

$a = Period::make('2021-01-01', '2021-02-01');
$b = Period::make('2021-02-01', '2021-02-28');

$a->overlapsWith($b); // true

The length of a period will also include both boundaries:

$a = Period::make('2021-01-01', '2021-01-31');

$a->length(); // 31

It's possible to override the boundary behaviour:

$a = Period::make('2021-01-01', '2021-02-01', boundaries: Boundaries::EXCLUDE_END());
$b = Period::make('2021-02-01', '2021-02-28', boundaries: Boundaries::EXCLUDE_END());

$a->overlapsWith($b); // false

There are four types of boundary exclusion:

Boundaries::EXCLUDE_NONE();
Boundaries::EXCLUDE_START();
Boundaries::EXCLUDE_END();
Boundaries::EXCLUDE_ALL();

Reference

The Period class offers a rich API to interact and compare with other periods and collections of periods. Take into account that only periods with the same precision can be compared:

startsBefore(DateTimeInterface $date): bool: whether a period starts before a given date.
startsBeforeOrAt(DateTimeInterface $date): bool: whether a period starts before or at a given date.
startsAfter(DateTimeInterface $date): bool: whether a period starts after a given date.
startsAfterOrAt(DateTimeInterface $date): bool: whether a period starts after or at a given date.
startsAt(DateTimeInterface $date): bool: whether a period starts at a given date.
endsBefore(DateTimeInterface $date): bool: whether a period ends before a given date.
endsBeforeOrAt(DateTimeInterface $date): bool: whether a period end before or at a given date.
endsAfter(DateTimeInterface $date): bool: whether a period ends after a given date.
endsAfterOrAt(DateTimeInterface $date): bool: whether a period end after or at a given date.
endsAt(DateTimeInterface $date): bool: whether a period starts ends at a given date.
overlapsWith(Period $period): bool: whether a period overlaps with another period.
touchesWith(Period $other): bool: whether a period touches with another period.
contains(DateTimeInterface|Period $other): bool: whether a period contains another period or a single date.
equals(Period $period): bool: whether a period equals another period.

On top of comparisons, the Period class also offers a bunch of operations:

`overlap(Period ...$others): ?static`

Overlaps two or more periods on each other. The resulting period will be the union of all other periods combined.

`overlapAny(Period ...$others): PeriodCollection`

Overlaps two or more periods on each other. Whenever two or more periods overlap, that overlapping period is added to a collection which will be returned as the final result.

`subtract(Period ...$others): PeriodCollection`

Subtracts one or more periods from the main period. This is the inverse operation of overlap.

`gap(Period $period): ?static`

Gets the gap between two periods, or 0 if the periods overlap.

`diffSymmetric(Period $other): PeriodCollection`

Performs a symmetric diff between two periods.

`renew(): static`

Renew the current period, creating a new period with the same length that happens after the current period.

Next, the Period class also has some getters:

isStartIncluded(): bool
isStartExcluded(): bool
isEndIncluded(): bool
isEndExcluded(): bool
start(): DateTimeImmutable
includedStart(): DateTimeImmutable
end(): DateTimeImmutable
includedEnd(): DateTimeImmutable
ceilingEnd(Precision::SECOND): DateTimeImmutable
length(): int
duration(): PeriodDuration
precision(): Precision
boundaries(): Boundaries

The PeriodCollection class represents a collection of periods and has some useful methods on its own:

`overlapAll(PeriodCollection ...$others): PeriodCollection`

Overlaps all collection periods on each other.

`subtract(PeriodCollection|Period ...$others): PeriodCollection`

Subtracts a period or a collection of periods from a period collection.

`boundaries(): ?Period`

Creates a new period representing the outer boundaries of the collection.

`gaps(): static`

Gives the gaps for all periods within this collection.

`intersect(Period $intersection): static`

Intersects given period with every period within a collection. The result is a new collection of overlapping periods between given period and every period in the collection. When there's no overlap, the original period is discarded.

`union(): static`

Merges all periods in collection with overlapping ranges.

Finally, there are a few utility methods available on PeriodCollection as well:

add(Period ...$periods): static
map(Closure $closure): static:
reduce(Closure $closure, $initial = null): mixed:
filter(Closure $closure): static:
isEmpty(): bool:

Compatibility

You can construct a Period from any type of DateTime object such as Carbon:

Period::make(Carbon::make('2021-01-01'), Carbon::make('2021-01-02'));

Note that as soon as a period is constructed, all further operations on it are immutable. There's never the danger of changing the input dates.

You can iterate a Period like a regular DatePeriod with the precision specified on creation:

$datePeriod = Period::make(Carbon::make('2021-01-01'), Carbon::make('2021-01-31'));

foreach ($datePeriod as $date) {
    /** @var DateTimeImmutable $date */
    // 2021-01-01
    // 2021-01-02
    // ...
    // (31 iterations)
}

$timePeriod = Period::make(Carbon::make('2021-01-01 00:00:00'), Carbon::make('2021-01-01 23:59:59'), Precision::HOUR());

foreach ($timePeriod as $time) {
    /** @var DateTimeImmutable $time */
    // 2021-01-01 00:00:00
    // 2021-01-01 01:00:00
    // ...
    // (24 iterations)
}

Visualizing periods

You can visualize one or more Period objects as well as PeriodCollection objects to see how they related to one another:

$visualizer = new Visualizer(["width" => 27]);

$visualizer->visualize([
    "A" => Period::make('2021-01-01', '2021-01-31'),
    "B" => Period::make('2021-02-10', '2021-02-20'),
    "C" => Period::make('2021-03-01', '2021-03-31'),
    "D" => Period::make('2021-01-20', '2021-03-10'),
    "OVERLAP" => new PeriodCollection(
        Period::make('2021-01-20', '2021-01-31'),
        Period::make('2021-02-10', '2021-02-20'),
        Period::make('2021-03-01', '2021-03-10')
    ),
]);

And visualize will return the following string:

A          [========]
B                      [==]
C                           [========]
D               [==============]
OVERLAP         [===]  [==] [==]

The visualizer has a configurable width provided upon creation which will control the bounds of the displayed periods:

$visualizer = new Visualizer(["width" => 10]);

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you've found a bug regarding security please mail security@spatie.be instead of using the issue tracker.

Postcardware

You're free to use this package, but if it makes it to your production environment we highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using.

Our address is: Spatie, Kruikstraat 22, 2021 Antwerp, Belgium.

We publish all received postcards on our company website.

Credits

License

The MIT License (MIT). Please see License File for more information.