A helper to query and format a set of opening hours

With spatie/opening-hours you create an object that describes a business' opening hours, which you can query for open or closed on days or specific dates, or use to present the times per day.

A set of opening hours is created by passing in a regular schedule, and a list of exceptions.

$openingHours = OpeningHours::create([
    'monday' => ['09:00-12:00', '13:00-18:00'],
    'tuesday' => ['09:00-12:00', '13:00-18:00'],
    'wednesday' => ['09:00-12:00'],
    'thursday' => ['09:00-12:00', '13:00-18:00'],
    'friday' => ['09:00-12:00', '13:00-20:00'],
    'saturday' => ['09:00-12:00', '13:00-16:00'],
    'sunday' => [],
    'exceptions' => [
        '2016-11-11' => ['09:00-12:00'],
        '2016-12-25' => [],
    ],
]);

The object can be queried for a day in the week, which will return a result based on the regular schedule:

// Open on Mondays:
$openingHours->isOpenOn('monday'); // true

// Closed on Sundays:
$openingHours->isOpenOn('sunday'); // false

It can also be queried for a specific date and time:

// Closed because it's after hours:
$openingHours->isOpenAt(new DateTime('2016-09-26 19:00:00')); // false

// Closed because Christmas was set as an exception
$openingHours->isOpenAt(new DateTime('2016-12-25')); // false

It can also return arrays of opening hours for a week or a day:

// OpeningHoursForDay object for the regular schedule
$openingHours->forDay('monday');

// OpeningHoursForDay[] for the regular schedule, keyed by day name
$openingHours->forWeek();

// OpeningHoursForDay object for a specific day
$openingHours->forDate(new DateTime('2016-12-25'));

// OpeningHoursForDay[] of all exceptions, keyed by date
$openingHours->exceptions();

Read the usage section for the full api.

Spatie is a webdesign agency based in Antwerp, Belgium. You'll find an overview of all our open source projects on our website.

Postcardware

You're free to use this package (it's MIT-licensed), but if it makes it to your production environment you are required to send us a postcard from your hometown, mentioning which of our package(s) you are using.

Our address is: Spatie, Samberstraat 69D, 2060 Antwerp, Belgium.

The best postcards will get published on the open source page on our website.

Installation

You can install the package via composer:

composer require spatie/opening-hours

Usage

The package should only be used through the OpeningHours class. There are also three value object classes used throughout, Time, which represents a single time, TimeRange, which represents a period with a start and an end, and openingHoursForDay, which represents a set of TimeRanges which can't overlap.

Spatie\OpeningHours\OpeningHours

OpeningHours::create(array $data): Spatie\OpeningHours\OpeningHours

Static factory method to fill the set of opening hours.

$openingHours = OpeningHours::create([
    'monday' => ['09:00-12:00', '13:00-18:00'],
    // ...
]);

Not all days are mandatory, if a day is missing, it will be set as closed.

OpeningHours::fill(array $data): Spatie\OpeningHours\OpeningHours

The same as create, but non-static.

$openingHours = (new OpeningHours)->fill([
    'monday' => ['09:00-12:00', '13:00-18:00'],
    // ...
]);

OpeningHours::forWeek(): Spatie\OpeningHours\OpeningHoursForDay[]

Returns an array of OpeningHoursForDay objects for a regular week.

$openingHours->forWeek();

OpeningHours::forDay(string $day): Spatie\OpeningHours\OpeningHoursForDay

Returns an OpeningHoursForDay object for a regular day. A day is lowercase string of the english day name.

$openingHours->forDay('monday');

OpeningHours::forDate(DateTime $dateTime): Spatie\OpeningHours\OpeningHoursForDay

Returns an OpeningHoursForDay object for a specific date. It looks for an exception on that day, and otherwise it returns the opening hours based on the regular schedule.

$openingHours->forDate(new DateTime('2016-12-25'));

OpeningHours::exceptions(): Spatie\OpeningHours\OpeningHoursForDay[]

Returns an array of all OpeningHoursForDay objects for exceptions, keyed by a Y-m-d date string.

$openingHours->exceptions();

OpeningHours::isOpenOn(string $day): bool

Checks if the business is op on a day in the regular schedule.

$openingHours->isOpenOn('saturday');

OpeningHours::isClosedOn(string $day): bool

Checks if the business is closed on a day in the regular schedule.

$openingHours->isClosedOn('sunday');

OpeningHours::isOpenAt(DateTime $dateTime): bool

Checks if the business is open on a specific day, at a specific time.

$openingHours->isOpenAt(new DateTime('2016-26-09 20:00'));

OpeningHours::isClosedAt(DateTime $dateTime): bool

Checks if the business is closed on a specific day, at a specific time.

$openingHours->isClosedAt(new DateTime('2016-26-09 20:00'));

OpeningHours::isOpen(): bool

Checks if the business is open right now.

$openingHours->isOpen();

OpeningHours::isClosed(): bool

Checks if the business is closed right now.

$openingHours->isClosed();

Spatie\OpeningHours\OpeningHoursForDay

This class is meant as read-only. It implements ArrayAccess, Countable and IteratorAggregate so you can process the list of TimeRanges in an array-like way.

Spatie\OpeningHours\TimeRange

Value object describing a period with a start and an end time. Can be casted to a string in a H:i-H:i format.

Spatie\OpeningHours\Time

Value object describing a single time. Can be casted to a string in a H:i format.

Changelog

Please see CHANGELOG for more information what has changed recently.

Testing

$ composer test

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email freek@spatie.be instead of using the issue tracker.

Credits

• Sebastian De Deyne
• All Contributors

About Spatie

Spatie is a webdesign agency based in Antwerp, Belgium. You'll find an overview of all our open source projects on our website.

License

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