Repository files navigation

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 ofDateTime implementation,making this package compatible with customDateTime implementations likeCarbon(seecmixin/enhanced-period toconvert directly from and to CarbonPeriod).

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

We invest a lot of resources into creatingbest in class open source packages. You can support us bybuying 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 onour contact page. We publish all received postcards onour virtual postcard wall.

You can install the package via composer:

composer require spatie/period

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 itsprecision andboundaries. UsingPeriod::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.

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 on2021-01-15.But what if the first period ends at2021-01-15 10:00:00,while the second starts at2021-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 foundhere.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()

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();

ThePeriod 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 periodor a single date.
• equals(Period $period): bool: whether a period equals another period.

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

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

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.

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

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

Performs asymmetric diff between two periods.

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

Next, thePeriod 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

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

Overlaps all collection periods on each other.

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

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

Gives the gaps for all periods within this collection.

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.

Merges all periods in collection with overlapping ranges.

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

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

You can construct aPeriod from any type ofDateTime 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 aPeriod like a regularDatePeriod with the precision specified on creation:

$datePeriod = Period::make(Carbon::make('2021-01-01'), Carbon::make('2021-01-31'));foreach ($datePeriodas$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 ($timePeriodas$time) {/** @var DateTimeImmutable $time */// 2021-01-01 00:00:00// 2021-01-01 01:00:00// ...// (24 iterations)}

You can visualize one or morePeriod objects as well asPeriodCollectionobjects to see how they related to one another:

$visualizer =newVisualizer(["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" =>newPeriodCollection(        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 creationwhich will control the bounds of the displayed periods:

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

composertest

Please seeCHANGELOG for more information on what has changed recently.

Please seeCONTRIBUTING for details.

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

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 postcardson our company website.

• Brent Roose
• All Contributors

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