README

Opening Hours for Laravel

Opening hours, seasonal schedules, holidays and bookable availability for any Eloquent model — clinics, shops, venues, pickup points. Overnight ranges, yearly and Easter-based exceptions, one explicit DST rule, and capacity-aware booking slots fed by any busy-period source.

Installation

Requires PHP 8.4, Laravel 12 or 13, and SQLite, PostgreSQL or MySQL.

composer require roundly-consulting/opening-hours-for-laravel
php artisan vendor:publish --tag="opening-hours-migrations"
php artisan migrate

If the models that own opening hours use UUID or ULID keys, set OPENING_HOURS_KEY_TYPE (uuid / ulid) before running the migrations.

Usage

Make a model an owner:

use Illuminate\Database\Eloquent\Model;
use RoundlyConsulting\OpeningHours\Concerns\HasOpeningHours;
use RoundlyConsulting\OpeningHours\Contracts\OpeningHoursOwner;

final class Clinic extends Model implements OpeningHoursOwner
{
    use HasOpeningHours;
}

Give it hours and exceptions, then ask questions:

use RoundlyConsulting\OpeningHours\Facades\OpeningHours;

OpeningHours::sync($clinic, [
    'timezone' => 'Europe/Bratislava',
    'week' => [
        'monday' => ['08:00-12:00', '13:00-17:00'],
        'friday' => ['08:00-15:00'],
        'saturday' => ['22:00-03:00'],                              // overnight: ends 03:00 on Sunday
    ],
    'exceptions' => [['date' => '12-25', 'label' => 'Christmas']],  // every year, closed
]);

OpeningHours::exceptions($clinic)->closed('2026-10-16', label: 'Staff training');

$hours = OpeningHours::for($clinic);
$hours->isOpen();                                // right now
$hours->nextClose();                             // ?CarbonImmutable, in the calendar's timezone
$hours->forDate('2026-10-12')->toString();       // "08:00–12:00, 13:00–17:00"
$hours->forDate('2026-10-16')->toString();       // "Closed"

Offer bookable slots around the appointments already in your own table:

use RoundlyConsulting\OpeningHours\Availability\Providers\EloquentBusyPeriodProvider;

$busy = EloquentBusyPeriodProvider::for(Appointment::query())->columns(start: 'starts_at', end: 'ends_at');

$slots = $hours->availability()
    ->withBusyPeriods($busy)
    ->minNotice(minutes: 120)
    ->slots('2026-10-12', '2026-10-16')->duration(30)->get();   // free 30-minute slots

Documentation

The full documentation — configuration, every feature and its API, and testing — lives on our website: roundly-consulting.com/open-source/docs/opening-hours-for-laravel

Release notes are in CHANGELOG.md. To contribute, see the contributing guide.

Support our work

This package is free and open source, built and maintained by Roundly Consulting. If it saves you time, please consider supporting our open-source work — a one-time donation, a monthly pledge on Patreon or a crypto donation helps fund maintenance, new features and new packages.

License

The MIT License (MIT). See LICENSE.md.

roundly-consulting / opening-hours-for-laravel

Package info

Security

Fund package maintenance!

Statistics