• Stars
    star
    1,515
  • Rank 29,537 (Top 0.7 %)
  • Language
    PHP
  • License
    MIT License
  • Created over 5 years ago
  • Updated 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Complex period comparisons

Complex period comparisons

Latest Version on Packagist Quality Score Total Downloads

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 [email protected] 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.

More Repositories

1

laravel-permission

Associate users with roles and permissions
PHP
11,600
star
2

laravel-medialibrary

Associate files with Eloquent models
PHP
5,427
star
3

laravel-backup

A package to backup your Laravel app
PHP
5,337
star
4

laravel-activitylog

Log activity inside your Laravel app
PHP
5,046
star
5

browsershot

Convert HTML to an image, PDF or string
PHP
4,434
star
6

laravel-query-builder

Easily build Eloquent queries from API requests
PHP
3,675
star
7

laravel-analytics

A Laravel package to retrieve pageviews and other data from Google Analytics
PHP
2,948
star
8

image-optimizer

Easily optimize images using PHP
PHP
2,450
star
9

async

Easily run code asynchronously
PHP
2,401
star
10

crawler

An easy to use, powerful crawler implemented in PHP. Can execute Javascript.
PHP
2,400
star
11

laravel-responsecache

Speed up a Laravel app by caching the entire response
PHP
2,248
star
12

data-transfer-object

Data transfer objects with batteries included
PHP
2,220
star
13

laravel-translatable

Making Eloquent models translatable
PHP
2,030
star
14

laravel-sitemap

Create and generate sitemaps with ease
PHP
2,011
star
15

dashboard.spatie.be

The source code of dashboard.spatie.be
PHP
1,940
star
16

laravel-fractal

An easy to use Fractal wrapper built for Laravel and Lumen applications
PHP
1,845
star
17

package-skeleton-laravel

A skeleton repository for Spatie's Laravel Packages
PHP
1,714
star
18

laravel-collection-macros

A set of useful Laravel collection macros
PHP
1,602
star
19

laravel-newsletter

Manage Mailcoach and MailChimp newsletters in Laravel
PHP
1,570
star
20

checklist-going-live

The checklist that is used when a project is going live
1,489
star
21

laravel-tags

Add tags and taggable behaviour to your Laravel app
PHP
1,454
star
22

opening-hours

Query and format a set of opening hours
PHP
1,340
star
23

eloquent-sortable

Sortable behaviour for Eloquent models
PHP
1,268
star
24

laravel-cookie-consent

Make your Laravel app comply with the crazy EU cookie law
PHP
1,268
star
25

schema-org

A fluent builder Schema.org types and ld+json generator
PHP
1,263
star
26

laravel-sluggable

An opinionated package to create slugs for Eloquent models
PHP
1,236
star
27

laravel-searchable

Pragmatically search through models and other sources
PHP
1,217
star
28

pdf-to-image

Convert a pdf to an image
PHP
1,207
star
29

once

A magic memoization function
PHP
1,159
star
30

laravel-honeypot

Preventing spam submitted through forms
PHP
1,134
star
31

laravel-mail-preview

A mail driver to quickly preview mail
PHP
1,134
star
32

laravel-image-optimizer

Optimize images in your Laravel app
PHP
1,121
star
33

laravel-google-calendar

Manage events on a Google Calendar
PHP
1,119
star
34

regex

A sane interface for php's built in preg_* functions
PHP
1,097
star
35

laravel-data

Powerful data objects for Laravel
PHP
1,073
star
36

image

Manipulate images with an expressive API
PHP
1,064
star
37

array-to-xml

A simple class to convert an array to xml
PHP
1,056
star
38

laravel-settings

Store strongly typed application settings
PHP
1,054
star
39

laravel-uptime-monitor

A powerful and easy to configure uptime and ssl monitor
PHP
992
star
40

laravel-multitenancy

Make your Laravel app usable by multiple tenants
PHP
988
star
41

db-dumper

Dump the contents of a database
PHP
987
star
42

laravel-model-states

State support for models
PHP
968
star
43

laravel-view-models

View models in Laravel
PHP
963
star
44

simple-excel

Read and write simple Excel and CSV files
PHP
930
star
45

laravel-web-tinker

Tinker in your browser
JavaScript
925
star
46

laravel-db-snapshots

Quickly dump and load databases
PHP
889
star
47

laravel-mix-purgecss

Zero-config Purgecss for Laravel Mix
JavaScript
887
star
48

laravel-schemaless-attributes

Add schemaless attributes to Eloquent models
PHP
880
star
49

blender

The Laravel template used for our CMS like projects
PHP
879
star
50

laravel-webhook-client

Receive webhooks in Laravel apps
PHP
877
star
51

calendar-links

Generate add to calendar links for Google, iCal and other calendar systems
PHP
877
star
52

laravel-menu

Html menu generator for Laravel
PHP
854
star
53

laravel-webhook-server

Send webhooks from Laravel apps
PHP
842
star
54

phpunit-watcher

A tool to automatically rerun PHPUnit tests when source code changes
PHP
831
star
55

laravel-failed-job-monitor

Get notified when a queued job fails
PHP
826
star
56

laravel-model-status

Easily add statuses to your models
PHP
818
star
57

laravel-schedule-monitor

Monitor scheduled tasks in a Laravel app
PHP
800
star
58

form-backend-validation

An easy way to validate forms using back end logic
JavaScript
800
star
59

temporary-directory

A simple class to work with a temporary directory
PHP
796
star
60

laravel-feed

Easily generate RSS feeds
PHP
789
star
61

laravel-server-monitor

Don't let your servers just melt down
PHP
769
star
62

fork

A lightweight solution for running code concurrently in PHP
PHP
751
star
63

laravel-tail

An artisan command to tail your application logs
PHP
726
star
64

enum

Strongly typed enums in PHP supporting autocompletion and refactoring
PHP
726
star
65

valuestore

Easily store some values
PHP
722
star
66

laravel-package-tools

Tools for creating Laravel packages
PHP
722
star
67

geocoder

Geocode addresses to coordinates
PHP
709
star
68

pdf-to-text

Extract text from a pdf
PHP
707
star
69

laravel-event-sourcing

The easiest way to get started with event sourcing in Laravel
PHP
700
star
70

ssh

A lightweight package to execute commands over an SSH connection
PHP
696
star
71

menu

Html menu generator
PHP
688
star
72

laravel-url-signer

Create and validate signed URLs with a limited lifetime
PHP
685
star
73

ssl-certificate

A class to validate SSL certificates
PHP
675
star
74

laravel-route-attributes

Use PHP 8 attributes to register routes in a Laravel app
PHP
674
star
75

laravel-validation-rules

A set of useful Laravel validation rules
PHP
663
star
76

url

Parse, build and manipulate URL's
PHP
659
star
77

laravel-html

Painless html generation
PHP
654
star
78

laravel-health

Check the health of your Laravel app
PHP
648
star
79

laravel-event-projector

Event sourcing for Artisans πŸ“½
PHP
642
star
80

laravel-server-side-rendering

Server side rendering JavaScript in your Laravel application
PHP
636
star
81

vue-tabs-component

An easy way to display tabs with Vue
JavaScript
626
star
82

macroable

A trait to dynamically add methods to a class
PHP
621
star
83

laravel-csp

Set content security policy headers in a Laravel app
PHP
614
star
84

laravel-blade-javascript

A Blade directive to export variables to JavaScript
PHP
608
star
85

laravel-cors

Send CORS headers in a Laravel application
PHP
607
star
86

laravel-translation-loader

Store your translations in the database or other sources
PHP
602
star
87

vue-table-component

A straight to the point Vue component to display tables
JavaScript
591
star
88

activitylog

A very simple activity logger to monitor the users of your website or application
PHP
586
star
89

http-status-check

CLI tool to crawl a website and check HTTP status codes
PHP
584
star
90

phpunit-snapshot-assertions

A way to test without writing actual testΒ cases
PHP
584
star
91

laravel-queueable-action

Queueable actions in Laravel
PHP
584
star
92

laravel-short-schedule

Schedule artisan commands to run at a sub-minute frequency
PHP
579
star
93

laravel-onboard

A Laravel package to help track user onboarding steps
PHP
579
star
94

freek.dev

The sourcecode of freek.dev
PHP
571
star
95

server-side-rendering

Server side rendering JavaScript in a PHP application
PHP
568
star
96

laravel-pdf

Create PDF files in Laravel apps
PHP
563
star
97

string

String handling evolved
PHP
558
star
98

ray

Debug with Ray to fix problems faster
PHP
540
star
99

laravel-http-logger

Log HTTP requests in Laravel applications
PHP
538
star
100

laravel-blade-x

Use custom HTML components in your Blade views
PHP
533
star