Weave Code
Opening Hours Laravel Package
spatie/opening-hours
spatie/opening-hours lets you define business opening hours as a weekly schedule plus exceptions, then query whether you’re open or closed on a day or specific date and present times per day. It also works with Carbon via cmixin/business-time.
A helper to query and format a set of opening hours
Frequently asked questions about Opening Hours
- How do I install spatie/opening-hours in a Laravel project?
- Install it with Composer by running composer require spatie/opening-hours. It is a framework-agnostic PHP library, so there is no service provider, facade, config file, or migration to publish. You can use the OpeningHours class directly in a service, job, or controller.
- Is spatie/opening-hours a Laravel package or a plain PHP library?
- It is a plain, dependency-light PHP library rather than a traditional Laravel package. It ships no service provider, facade, config file, or migration. That makes it easy to drop into a Laravel service layer without fighting framework conventions.
- How do I define weekly opening hours and exceptions?
- Create an OpeningHours instance with OpeningHours::create() and pass a weekly schedule array keyed by day, such as monday and friday, with time ranges like 09:00-12:00. You can also pass a list of exceptions for specific dates. Exceptions are useful for holidays, one-off closures, or special hours.
- How do I check if a business is open now or on a specific date?
- Use query methods such as isOpenAt, isOpenOn, nextOpen, nextClose, currentOpenRange, forWeek, and forDate. These cover common requirements like open-now badges, next-opening messages, weekly display, and holiday exceptions. You pass DateTime objects that should match the schedule timezone unless you configure conversion.
- Does spatie/opening-hours support timezones and daylight saving time?
- Yes, the library supports a schedule timezone and separates input and output timezones, which is useful for multi-region tenants. DST transitions, especially around overnight ranges and 24:00 overflow, are the classic source of subtle bugs, so add explicit test cases. Passed DateTime objects are assumed to match the schedule timezone unless you configure conversion.
- Can I use spatie/opening-hours with Carbon?
- Yes, it works directly with Carbon through the cmixin/business-time package. That lets Carbon-centric codebases stay idiomatic while using opening-hours features. You still construct the OpeningHours object from your schedule array.
- How should I store opening hours in a Laravel database?
- The schedule is a plain array, so it maps naturally to a JSON column on an existing model such as a store, location, branch, or provider. Alternatively, store it in a separate schedules table if you need independent editing, approval, or audit history. Hydrate the object with OpeningHours::create($array, $timezone) and keep Eloquent aware only through a cast or accessor.
- What are the performance concerns with filters in spatie/opening-hours?
- Filters are closures evaluated per date with no caching, and the README explicitly warns about this. Do not put database or API calls inside a filter in a Laravel app, because that creates a latent performance and correctness hazard. Keep filters pure and lightweight, and enforce that by convention.
- What happens if my opening hour ranges overlap?
- Overlapping ranges throw an exception by default. That is acceptable, but user-entered schedules need validation or merge handling before construction. The library provides mergeOverlappingRanges and createAndMergeOverlappingRanges to help with that.
- Which PHP and Laravel versions are supported, and is the package maintained?
- The package is framework-agnostic and works with any Laravel version on a supported PHP runtime, but you should confirm the PHP and Carbon versions of the release you pin against your application. The repository has a strong Spatie signal, yet metadata such as zero dependents and an anomalous last release date should be verified on Packagist before pinning. Treat those as data-quality artifacts rather than popularity signals.
Weaver
How can I help you explore Laravel packages today?