README

Add booking functionality to any Eloquent model. Turn your models into bookable resources with time-based reservations, capacity management, planning constraints, overlap detection, and an event-driven architecture.

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Core Concepts
• Advanced Features
• Documentation
• Testing
• Contributing & Credits

Features

• 🚀 Make any Eloquent model bookable with a single trait
• 📅 Advanced time period management powered by spatie/period
• 🏢 Resource capacity control with configurable concurrency limits
• 📋 Planning constraints for weekday and time-window restrictions
• 🔍 Overlap detection and conflict prevention
• 🎯 Event-driven architecture for audit trails and integrations
• 🗂️ Polymorphic relationships for flexible booker and resource types
• 🔗 Related bookings with parent-child relationships
• 🔄 Automatic synchronization of resources and planning via model events
• 🛡️ Transaction safety with automatic rollback on failures

Requirements

Installation

Install the package via Composer:

composer require masterix21/laravel-bookings

Publish and run the migrations:

php artisan vendor:publish --tag="bookings-migrations"
php artisan migrate

Optionally, publish the config file:

php artisan vendor:publish --tag="bookings-config"

See the installation guide for optional migrations and upgrade notes.

Quick Start

1. Make a model bookable

Add the IsBookable trait to any model. A BookableResource is created and kept in sync automatically.

use Masterix21\Bookings\Models\Concerns\Bookable;
use Masterix21\Bookings\Models\Concerns\IsBookable;

class Room extends Model implements Bookable
{
    use IsBookable;

    protected $fillable = ['name', 'capacity'];
}

2. Configure the bookable resource

Each bookable model exposes its BookableResource, where you set availability and capacity:

$room = Room::create(['name' => 'Deluxe Suite', 'capacity' => 4]);

$room->bookableResource->update([
    'max' => 1,            // Maximum concurrent bookings
    'size' => 4,           // Resource capacity
    'is_bookable' => true,
    'is_visible' => true,
]);

3. Make a booking

use Masterix21\Bookings\Actions\BookResource;
use Spatie\Period\Period;
use Spatie\Period\PeriodCollection;

$periods = PeriodCollection::make([
    Period::make('2024-12-25', '2024-12-27'),
]);

$booking = (new BookResource())->run(
    periods: $periods,
    bookableResource: $room->bookableResource,
    booker: auth()->user(),
    label: 'Christmas Holiday',
    meta: ['guests' => 2],
);

Overlapping bookings are rejected automatically:

use Masterix21\Bookings\Exceptions\BookingResourceOverlappingException;

try {
    $booking = (new BookResource())->run(/* ... */);
} catch (BookingResourceOverlappingException $e) {
    return response()->json(['error' => 'Time slot already booked'], 409);
}

See the getting started guide for a full walkthrough.

Core Concepts

Advanced Features

Each feature below is summarized here and documented in full under docs/.

Booking lifecycle callbacks

Hook custom logic before and after a booking is persisted with onBookingSaving() and onBookingSaved() — useful for multi-tenancy, logging, or side effects. → docs/actions.md

Custom resource synchronization

Add the SyncBookableResource trait and implement syncBookableResource() to push data from your model (visibility, capacity, availability) into its BookableResource automatically on save. → docs/synchronization.md

Planning source pattern

Add the SyncBookablePlanning trait so a business model (rate, special offer, seasonal rule) becomes the single source of truth for a resource's availability, with bidirectional navigation between source and planning. → docs/synchronization.md

Related bookings

Link bookings with parent-child relationships (room + parking, appointment + follow-up). Each booking keeps an independent lifecycle, and children survive parent deletion. Requires an optional migration. → docs/related-bookings.md

Planning constraints

Define when a resource can be booked through BookablePlanning records — available weekdays plus starts_at/ends_at windows. → docs/models.md

Events

The booking lifecycle emits events (BookingInProgress, BookingCompleted, BookingFailed, BookingChanging, BookingChanged, BookingChangeFailed) for audit trails and integrations. → docs/events.md

Checking availability

$room->isBookedAt(now());            // bool
$room->bookedPeriodsOfDate(today()); // booked periods for a date
$room->bookings;                     // all bookings for the resource

Documentation

Examples

• 🏨 Hotel Booking System
• 🚗 Car Rental System
• 🍽️ Restaurant Reservations
• 📅 Service Appointments

Testing

composer test           # run the test suite
composer test-coverage  # run with coverage
composer analyse        # run static analysis (PHPStan)

See docs/testing.md for testing strategies.

Contributing & Credits

• Please see CONTRIBUTING for contribution guidelines.
• Please see CHANGELOG for recent changes.
• Report security vulnerabilities via our security policy.

Created and maintained by Luca Longo and all contributors.

License

The MIT License (MIT). See the License File for details.