README

A small, framework-agnostic PHP library for computing bookable availability and time slots. You describe when something is available — with a recurring weekly schedule or a single date range — and Bookables turns that into concrete time ranges and ready-to-book slots for any window of dates.

It's a pure domain library: no framework coupling, no database, no HTTP. Drop it into any PHP application (Laravel, Symfony, plain PHP, …) that needs to answer "when can this resource be booked?". It builds on nesbot/carbon for date/time math and league/period for the Period value object used to represent ranges and slots.

Requirements

• PHP >=8.4 <9.0
• ext-json

Installation

Install via Composer:

composer require puntodev/bookables

Concepts

The library is organized around a simple pipeline:

WeeklySchedule  ──▶  Agenda  ──▶  TimeSlotter  ──▶  bookable slots
 (availability)     (concrete       (slices ranges     (Period[])
                     date ranges)    into slots)

All ranges and slots are returned as League\Period\Period objects. Call ->toIso8601() (or any Period method) to inspect them.

Usage

1. Define a weekly schedule

A WeeklySchedule describes, for each day of the week, the time ranges during which the resource is available. Build one from an array or from JSON — both validate the input and throw an Exception if it's malformed.

use Puntodev\Bookables\WeeklySchedule;

$schedule = WeeklySchedule::fromArray([
    'hours_in_advance' => 24,
    'disable_all' => false,
    'daily' => [
        'Mon' => [
            ['start' => '08:00', 'end' => '12:00'],
            ['start' => '14:00', 'end' => '18:00'],
        ],
        'Tue' => [['start' => '09:00', 'end' => '17:00']],
        'Wed' => [],
        // ...Thu, Fri, Sat, Sun
    ],
]);

The JSON form (handy for persisting a schedule in a database column):

$schedule = WeeklySchedule::fromJson(
    '{"hours_in_advance": 24, "disable_all": false, "daily": {"Sun":[{"start":"14:00","end":"15:00"}]}}'
);

$schedule->toJson();   // serialize back to a JSON string
$schedule->toArray();  // or to an array

There's also a ready-made sample schedule (Mon–Fri 08:00–12:00 & 14:00–18:00, Sat 10:00–12:00):

$schedule = WeeklySchedule::fromArray(WeeklySchedule::defaultWorkingHours());

Schedule JSON schema

2. Get available ranges from an agenda

An Agenda turns availability into the concrete date ranges that fall inside a requested [from, to] window.

use Carbon\CarbonImmutable;
use Puntodev\Bookables\Agenda\WeeklyScheduleAgenda;

$agenda = new WeeklyScheduleAgenda($schedule);

$ranges = $agenda->possibleRanges(
    CarbonImmutable::parse('2020-01-20'),
    CarbonImmutable::parse('2020-01-21'),
);

foreach ($ranges as $range) {
    echo $range->toIso8601(), PHP_EOL;
    // 2020-01-20T08:00:00.000000Z/2020-01-20T12:00:00.000000Z
    // 2020-01-20T14:00:00.000000Z/2020-01-20T18:00:00.000000Z
    // ...
}

For one-off availability that isn't weekly (e.g. a single open window), use SingleDateRangeAgenda. It returns the intersection of its fixed range with the requested window (or no range at all if they don't overlap):

use Puntodev\Bookables\Agenda\SingleDateRangeAgenda;

$agenda = new SingleDateRangeAgenda(
    CarbonImmutable::parse('2020-01-20 09:00'),
    CarbonImmutable::parse('2020-01-20 17:00'),
);

3. Turn ranges into bookable slots

A TimeSlotter slices ranges into the actual slots a user can book.

AgendaSlotter produces fixed-duration slots inside each of an agenda's ranges:

use Puntodev\Bookables\Slots\AgendaSlotter;

// 30-minute slots, back to back
$slotter = new AgendaSlotter($agenda, duration: 30);

$slots = $slotter->makeSlotsForDates(
    CarbonImmutable::parse('2020-01-23'),
    CarbonImmutable::parse('2020-01-23'),
);

// 2020-01-23T08:00:00.000000Z/2020-01-23T08:30:00.000000Z
// 2020-01-23T08:30:00.000000Z/2020-01-23T09:00:00.000000Z
// ...

You can reserve a gap before and/or after each appointment (in minutes). The stride between slot starts becomes duration + max(timeAfter, timeBefore):

// 50-minute appointments with a 10-minute gap after each → slots every 60 minutes
$slotter = new AgendaSlotter($agenda, duration: 50, timeAfter: 10);

// 2020-01-23T08:00:00.000000Z/2020-01-23T08:50:00.000000Z
// 2020-01-23T09:00:00.000000Z/2020-01-23T09:50:00.000000Z
// ...

DaySlotter ignores agendas entirely and lays a sliding window of slots across the full 24 hours of each day — useful when availability is "any time" and you only care about duration and stepping. When step is smaller than duration, slots overlap.

use Puntodev\Bookables\Slots\DaySlotter;

// 30-minute slots starting every 15 minutes
$slotter = new DaySlotter(duration: 30, step: 15);

$slots = $slotter->makeSlotsForDates(
    CarbonImmutable::parse('2020-01-23'),
    CarbonImmutable::parse('2020-01-23'),
);

// 2020-01-23T00:00:00.000000Z/2020-01-23T00:30:00.000000Z
// 2020-01-23T00:15:00.000000Z/2020-01-23T00:45:00.000000Z
// 2020-01-23T00:30:00.000000Z/2020-01-23T01:00:00.000000Z
// ...

Timezones

Agendas compute availability in the timezone of the Carbon instances you pass in. WeeklyScheduleAgenda interprets the schedule's HH:MM times in that timezone. Note that Period::toIso8601() renders in UTC (Z), so the same wall-clock schedule in different timezones produces different UTC output:

$tz = 'Pacific/Auckland';
$ranges = $agenda->possibleRanges(
    CarbonImmutable::parse('2020-01-20', $tz),
    CarbonImmutable::parse('2020-01-20', $tz),
);
// 08:00–12:00 Auckland time → 2020-01-19T19:00:00Z / 2020-01-19T23:00:00Z

Modeling your own bookable entities

The HasAgenda and TimeBookable contracts are there for your application to implement on its own models — for example, a professional or room that exposes an agenda:

use Puntodev\Bookables\Contracts\Agenda;
use Puntodev\Bookables\Contracts\HasAgenda;

class Professional implements HasAgenda
{
    public function agenda(): Agenda
    {
        return new WeeklyScheduleAgenda($this->weeklySchedule());
    }
}

Notes & caveats

• hours_in_advance is not enforced by the slotters. It's carried as metadata (available via hoursInAdvance()); filtering out slots that are too soon is the consuming application's responsibility.

• disable_all is enforced — a WeeklyScheduleAgenda over a disabled schedule yields no ranges.

• Ranges and slots are immutable League\Period\Period objects; all internal date math uses Carbon's immutable variants.

• Requested date ranges are capped. WeeklyScheduleAgenda, AgendaSlotter and DaySlotter generate one entry per day (and per slot) in the [from, to] window, so an unbounded range would exhaust memory. Each takes an optional maxDays argument (default 366) and throws Puntodev\Bookables\Exceptions\DateRangeTooLargeException when the window is larger. Pass 0 (or less) to disable the limit if you have your own bound:

  use Puntodev\Bookables\Exceptions\DateRangeTooLargeException;
  
  $agenda  = new WeeklyScheduleAgenda($schedule, maxDays: 92);
  $slotter = new AgendaSlotter($agenda, duration: 30, maxDays: 92);
  $slotter = new DaySlotter(duration: 30, step: 15, maxDays: 92);
  
  try {
      $slots = $slotter->makeSlotsForDates($from, $to);
  } catch (DateRangeTooLargeException $e) {
      // reject the request (e.g. HTTP 422)
  }

• Slot durations must be positive. AgendaSlotter (duration) and DaySlotter (duration, step) reject non-positive values with InvalidArgumentException; timeAfter/timeBefore must not be negative.

Testing

composer test

Generate an HTML coverage report:

composer test-coverage

Changelog

Please see CHANGELOG for what has changed recently.

Releasing

Releases are cut from GitHub and the changelog is kept in sync automatically:

1. Merge the pull requests you want to ship into master. Label them so the notes group nicely (security, enhancement, bug, dependencies, documentation); grouping is configured in .github/release.yml.
2. On GitHub, go to Releases → Draft a new release, create a vX.Y.Z tag following SemVer, and click Generate release notes.
3. Publish the release. Packagist picks up the new tag, and the update-changelog.yml workflow writes the release notes into CHANGELOG.md and commits them back to master.

The Unreleased section in the changelog is just an anchor — release notes flow from the published GitHub release, so there is no changelog to edit by hand.

Contributing

Please see CONTRIBUTING for details. In short: keep the library framework-agnostic, write everything in English, and include tests with every change.

Security

If you discover any security-related issues, please email mariano.goldman@puntodev.com.ar instead of using the issue tracker.

Credits

• Mariano Goldman

License

The MIT License (MIT). Please see the License File for more information.