Download the PHP package spatie/opening-hours without Composer
On this page you can find all versions of the php package spatie/opening-hours. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download spatie/opening-hours
More information about spatie/opening-hours
Files in spatie/opening-hours
Package opening-hours
Short Description A helper to query and format a set of opening hours
License MIT
Homepage https://github.com/spatie/opening-hours
Informations about the package opening-hours
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.
spatie/opening-hours
can be used directly on Carbon thanks
to cmixin/business-time so you can benefit
opening hours features directly on your enhanced date objects.
A set of opening hours is created by passing in a regular schedule, and a list of exceptions.
The object can be queried for a day in the week, which will return a result based on the regular schedule:
It can also be queried for a specific date and time:
It can also return arrays of opening hours for a week or a day:
On construction, you can set a flag for overflowing times across days. For example, for a nightclub opens until 3am on Friday and Saturday:
This allows the API to further at previous day's data to check if the opening hours are open from its time range.
You can add data in definitions then retrieve them:
In the example above, data are strings but it can be any kind of value. So you can embed multiple properties in an array.
For structure convenience, the data-hours couple can be a fully-associative array, so the example above is strictly equivalent to the following:
You can use the separator to
to specify multiple days at once, for the week or for exceptions:
The last structure tool is the filter, it allows you to pass closures (or callable function/method reference) that take a date as a parameter and returns the settings for the given date.
If a callable is found in the "exceptions"
property, it will be added automatically to filters so you can mix filters and exceptions both in the exceptions array. The first filter that returns a non-null value will have precedence over the next filters and the filters array has precedence over the filters inside the exceptions array.
Warning: We will loop on all filters for each date from which we need to retrieve opening hours and can neither predicate nor cache the result (can be a random function) so you must be careful with filters, too many filters or long process inside filters can have a significant impact on the performance.
It can also return the next open or close DateTime
from a given DateTime
.
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.
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:
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 TimeRange
s which can't overlap.
Spatie\OpeningHours\OpeningHours
OpeningHours::create(array $data, $timezone = null, $toutputTimezone = null): Spatie\OpeningHours\OpeningHours
Static factory method to fill the set of opening hours.
If no timezone is specified, OpeningHours
will just assume you always
pass DateTime
objects that have already the timezone matching your schedule.
If you pass a $timezone
as a second argument or via the array-key 'timezone'
(it can be either a DateTimeZone
object or a string
), then passed dates will
be converted to this timezone at the beginning of each method, then if the method
return a date object (such as nextOpen
, nextClose
, previousOpen
,
previousClose
, currentOpenRangeStart
or currentOpenRangeEnd
), then it's
converted back to original timezone before output so the object can reflect
a moment in user local time while OpeningHours
can stick in its own business
timezone.
Alternatively you can also specify both input and output timezone (using second and third argument) or using an array:
OpeningHours::mergeOverlappingRanges(array $schedule) : array
For safety sake, creating OpeningHours
object with overlapping ranges will throw an exception unless you pass explicitly 'overflow' => true,
in the opening hours array definition. You can also explicitly merge them.
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::forWeek(): Spatie\OpeningHours\OpeningHoursForDay[]
Returns an array of OpeningHoursForDay
objects for a regular week.
OpeningHours::forWeekCombined(): array
Returns an array of days. Array key is first day with same hours, array values are days that have the same working hours and OpeningHoursForDay
object.
OpeningHours::forWeekConsecutiveDays(): array
Returns an array of concatenated days, adjacent days with the same hours. Array key is first day with same hours, array values are days that have the same working hours and OpeningHoursForDay
object.
Warning: consecutive days are considered from Monday to Sunday without looping (Monday is not consecutive to Sunday) no matter the days order in initial data.
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::forDate(DateTimeInterface $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::exceptions(): Spatie\OpeningHours\OpeningHoursForDay[]
Returns an array of all OpeningHoursForDay
objects for exceptions, keyed by a Y-m-d
date string.
OpeningHours::isOpenOn(string $day): bool
Checks if the business is open (contains at least 1 range of open hours) on a day in the regular schedule.
If the given string is a date, it will check if it's open (contains at least 1 range of open hours) considering both regular day schedule and possible exceptions.
OpeningHours::isClosedOn(string $day): bool
Checks if the business is closed on a day in the regular schedule.
OpeningHours::isOpenAt(DateTimeInterface $dateTime): bool
Checks if the business is open on a specific day, at a specific time.
OpeningHours::isClosedAt(DateTimeInterface $dateTime): bool
Checks if the business is closed on a specific day, at a specific time.
OpeningHours::isOpen(): bool
Checks if the business is open right now.
OpeningHours::isClosed(): bool
Checks if the business is closed right now.
OpeningHours::isAlwaysOpen(): bool
Checks if the business is open 24/7, has no exceptions and no filters.
OpeningHours::isAlwaysClosed(): bool
Checks if the business is never open, has no exceptions and no filters.
OpeningHours
accept empty array or list with every week day empty with no prejudices.
If it's not a valid state in your domain, you should use this method to throw an exception or show an error.
OpeningHours::nextOpen
Returns next open DateTime
from the given DateTime
($dateTime
or from now if this parameter is null or omitted).
If a DateTimeImmutable
object is passed, a DateTimeImmutable
object is returned.
Set $searchUntil
to a date to throw an exception if no open time can be found before this moment.
Set $cap
to a date so if no open time can be found before this moment, $cap
is returned.
OpeningHours::nextClose
Returns next close DateTime
from the given DateTime
($dateTime
or from now if this parameter is null or omitted).
If a DateTimeImmutable
object is passed, a DateTimeImmutable
object is returned.
Set $searchUntil
to a date to throw an exception if no closed time can be found before this moment.
Set $cap
to a date so if no closed time can be found before this moment, $cap
is returned.
If the schedule is always open or always closed, there is no state change to found and therefore
nextOpen
(but also previousOpen
, nextClose
and previousClose
) will throw a MaximumLimitExceeded
You can catch it and react accordingly or you can use isAlwaysOpen
/ isAlwaysClosed
methods
to anticipate such case.
OpeningHours::previousOpen
Returns previous open DateTime
from the given DateTime
($dateTime
or from now if this parameter is null or omitted).
If a DateTimeImmutable
object is passed, a DateTimeImmutable
object is returned.
Set $searchUntil
to a date to throw an exception if no open time can be found after this moment.
Set $cap
to a date so if no open time can be found after this moment, $cap
is returned.
OpeningHours::previousClose
Returns previous close DateTime
from the given DateTime
($dateTime
or from now if this parameter is null or omitted).
If a DateTimeImmutable
object is passed, a DateTimeImmutable
object is returned.
Set $searchUntil
to a date to throw an exception if no closed time can be found after this moment.
Set $cap
to a date so if no closed time can be found after this moment, $cap
is returned.
OpeningHours::diffInOpenHours(DateTimeInterface $startDate, DateTimeInterface $endDate) : float
Return the amount of open time (number of hours as a floating number) between 2 dates/times.
OpeningHours::diffInOpenMinutes(DateTimeInterface $startDate, DateTimeInterface $endDate) : float
Return the amount of open time (number of minutes as a floating number) between 2 dates/times.
OpeningHours::diffInOpenSeconds(DateTimeInterface $startDate, DateTimeInterface $endDate) : float
Return the amount of open time (number of seconds as a floating number) between 2 dates/times.
OpeningHours::diffInClosedHours(DateTimeInterface $startDate, DateTimeInterface $endDate) : float
Return the amount of closed time (number of hours as a floating number) between 2 dates/times.
OpeningHours::diffInClosedMinutes(DateTimeInterface $startDate, DateTimeInterface $endDate) : float
Return the amount of closed time (number of minutes as a floating number) between 2 dates/times.
OpeningHours::diffInClosedSeconds(DateTimeInterface $startDate, DateTimeInterface $endDate) : float
Return the amount of closed time (number of seconds as a floating number) between 2 dates/times.
OpeningHours::currentOpenRange(DateTimeInterface $dateTime) : false | TimeRange
Returns a Spatie\OpeningHours\TimeRange
instance of the current open range if the
business is open, false if the business is closed.
start()
and end()
methods return Spatie\OpeningHours\Time
instances. Time
instances created from a date can be formatted with date information. This is useful
for ranges overflowing midnight:
OpeningHours::currentOpenRangeStart(DateTimeInterface $dateTime) : false | DateTime
Returns a DateTime
instance of the date and time since when the business is open if
the business is open, false if the business is closed.
Note: date can be the previous day if you use night ranges.
OpeningHours::currentOpenRangeEnd(DateTimeInterface $dateTime) : false | DateTime
Returns a DateTime
instance of the date and time until when the business will be open
if the business is open, false if the business is closed.
Note: date can be the next day if you use night ranges.
OpeningHours::createFromStructuredData(array|string $data, $timezone = null, $outputTimezone = null): Spatie\OpeningHours\OpeningHours
Static factory method to fill the set with a https://schema.org/OpeningHoursSpecification array or JSON string.
dayOfWeek
supports array of day names (Google-flavored) or array of day URLs (official schema.org specification).
OpeningHours::asStructuredData(strinf $format = 'H:i', string|DateTimeZone $timezone) : array
Returns a OpeningHoursSpecification as an array.
Spatie\OpeningHours\OpeningHoursForDay
This class is meant as read-only. It implements ArrayAccess
, Countable
and IteratorAggregate
so you can process the list of TimeRange
s in an array-like way.
Spatie\OpeningHours\TimeRange
Value object describing a period with a start and an end time. Can be cast to a string in a H:i-H:i
format.
Spatie\OpeningHours\Time
Value object describing a single time. Can be cast to a string in a H:i
format.
Adapters
OpenStreetMap
You can convert OpenStreetMap format to OpeningHours
object using osm-opening-hours (thanks to mgrundkoetter)
Changelog
Please see CHANGELOG for more information about what has changed recently.
Testing
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, 2018 Antwerp, Belgium.
We publish all received postcards on our company website.
Credits
- Sebastian De Deyne
- All Contributors
License
The MIT License (MIT). Please see License File for more information.