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

Why a time is unavailable

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

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 — a regular collection with available() and groupByDate() added, so map(), groupBy(), keyBy() or pluck() work as usual; first() returns the first ?Slot.
• Each Slot has start, end, available, remainingCapacity and reason. It is Arrayable and JsonSerializable: toArray(), json_encode() and response()->json() give start, end, available, remaining_capacity and reason, with ISO-8601 times in the output timezone — and a SlotCollection gives every slot in that shape, keys kept.
• nextAvailableSlot() looks search_days local days ahead and returns the slot that slots() over that window lists first. It searches in chunks, so it stays within max_query_days on its own — it throws QueryRangeTooLargeException only when one slot with its buffers is longer.
• The grid aligns on the local wall clock and stays correct across DST gaps, repeated fall-back hours 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). That window must fit within max_query_days: check(), isAvailable() and slot queries throw QueryRangeTooLargeException for a longer one before reading any hours or busy periods. 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]);
});