Availability and slots

Availability knows nothing about bookings — it asks a busy-period source what is occupied. availability() returns an immutable builder; every setter returns a copy:

use Carbon\CarbonImmutable;
use RoundlyConsulting\OpeningHours\Availability\BusyPeriod;
use RoundlyConsulting\OpeningHours\Facades\OpeningHours;

$availability = OpeningHours::for($clinic)->availability()
    ->withBusyPeriods(fn (CarbonImmutable $start, CarbonImmutable $end) => $bookings->between($start, $end))
    ->capacity(2)                           // parallel bookings (a range's own capacity wins)
    ->buffers(before: 5, after: 10)         // must fall inside opening hours by default
    ->minNotice(minutes: 120)
    ->horizon(days: 60);

$result = $availability->check($start, $end);   // AvailabilityResult
$result->available;                             // bool
$result->reason;                                // ?UnavailableReason: invalid_range, in_past, too_soon, too_far, closed, busy
$result->conflict;                              // ?BusyPeriod
$result->message();                             // translated reason
$availability->isAvailable($start, $end, weight: 1);

Settings

Method	Meaning
`withBusyPeriods($busy)`	Busy source: a BusyPeriodProvider, an iterable of BusyPeriod, or a closure (start, end) returning them.
`capacity(int)`	Default parallel capacity (≥ 1); a range’s own capacity wins; fallback 1.
`buffers(before:, after:, withinOpeningHours: true)`	Minutes blocked around each booking; by default they must fall inside opening hours. With withinOpeningHours: false, the closed part of a buffer counts the capacity of the range the booking starts in (before) or ends in (after).
`minNotice(minutes:)`	Earliest start = now + n real minutes.
`horizon(days:)`	Latest start = now + n calendar days on the local wall clock (inclusive); null = unlimited.
`at($instant)`	Evaluate as of this instant instead of now.

Why a time is unavailable

check() evaluates in a fixed order and reports the first failing reason; message() returns it translated:

Reason	When
`invalid_range`	The end is not after the start.
`in_past`	The start is before now.
`too_soon`	The start falls inside the minimum notice.
`too_far`	The start is beyond the horizon.
`closed`	Opening hours don’t cover the booking plus its buffers.
`busy`	Capacity is exceeded somewhere in the occupied window; conflict holds the first overlapping busy period.

Slots

$slots = $availability->slots('2026-10-01', '2026-10-07')     // whole local days, inclusive
    ->duration(30)->step(15)->alignTo(15)
    ->limit(200)
    ->get();                                                   // SlotCollection
$slots->groupByDate();                                         // ['2026-10-01' => [Slot, …], …]

foreach ($slots as $slot) {
    $slot->start;                                              // CarbonImmutable
    $slot->end;
    $slot->remainingCapacity;
}

$all = $availability->slots('2026-10-01', '2026-10-01')
    ->duration(60)
    ->includeUnavailable()                                     // also slots that failed on capacity
    ->get();
$all->available();                                             // only the bookable ones

$availability->slots('2026-10-01', '2026-10-01')->duration(60)->first();   // ?Slot
$availability->nextAvailableSlot(duration: 30);                // ?Slot
$availability->freePeriods('2026-10-01', '2026-10-01');        // list<Period>

slots($from, $to) takes dates (whole local days, inclusive) or instants (end exclusive). duration() is required; step() defaults to the duration; alignTo() defaults to the step and counts from local midnight.
weight() books several capacity units at once; includeUnavailable() also returns capacity failures (reason busy); limit() caps the result at limits.slots.
get() returns a SlotCollection with available(), groupByDate() and toArray(); first() returns the first ?Slot.
Each Slot has start, end, available, remainingCapacity and reason.
nextAvailableSlot() looks search_days local days ahead and searches in chunks, so it stays within max_query_days on its own.
The grid aligns on the local wall clock and stays correct across DST gaps and 30-minute shifts; multi-day slots (rentals) work like any other.

Capacity model

Open capacity is range.capacity ?? availability capacity ?? 1, and overlapping ranges take the maximum. A booking fits when usage + weight ≤ capacity at every moment of [start − before, end + after). With buffers(withinOpeningHours: false), the closed part of a buffer counts the capacity of the range the booking starts in (before) or ends in (after). Durations, notice and buffers are real elapsed time; the horizon is counted in calendar days on the local wall clock.

Check again when you book

Availability is a read. When you persist a booking, re-check inside your own lock or unique constraint — another request may book the same slot between your check and your insert:

use Illuminate\Support\Facades\Cache;

Cache::lock("book:{$vet->id}:{$start}", 10)->block(5, function () use ($availability, $vet, $start, $end): void {
    abort_unless($availability->isAvailable($start, $end), 409);

    Appointment::query()->create(['vet_id' => $vet->id, 'starts_at' => $start, 'ends_at' => $end]);
});

Show your open-source love

This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.

More ways to support, including crypto

By donating, you agree to our donation terms.

Support our open source work Join us on Patreon

Want this built into your product?

We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.

Get a quote in 48 hours Browse all packages