Download the PHP package aaronfrancis/reservable without Composer

Reservable

Eloquent model reservation/locking through Laravel's cache lock system.

This package allows you to temporarily "reserve" Eloquent models using Laravel's atomic cache locks. This is useful when you need to ensure exclusive access to a model for a period of time, such as during background processing.

Installation

Publish the migration:

Optionally publish the config:

Requirements

This package requires Laravel's database cache driver. Make sure your cache_locks table exists (created by Laravel's default cache migration).

The published migration adds generated columns to parse reservation keys into queryable columns. This allows efficient querying of reserved/unreserved models.

Supported databases: PostgreSQL, MySQL/MariaDB, SQLite

Usage

Add the Reservable trait to your model:

Reserve a model

The reserve() method returns true if the lock was acquired, or false if the model is already reserved.

Check if reserved

Release a reservation

Blocking reserve

Wait for a lock to become available instead of failing immediately:

Returns true if the lock was acquired, false if the wait time expired.

Reserve with callback

Automatically release the lock when your work is done:

The lock is released even if the callback throws an exception. Returns false if the lock couldn't be acquired.

Extend a reservation

Add more time to an existing reservation without releasing it:

Only reservations acquired by the current process can be extended.

Returns true if the reservation was extended, false if no active reservation exists or the current process does not own the lock.

Query scopes

Find unreserved models:

Find reserved models:

Note: These scopes return point-in-time results. By the time you try to reserve a model from the results, another process may have already reserved it. Use reserveFor for atomic find-and-reserve operations.

Find and reserve in one query:

The reserveFor scope filters to unreserved models, then atomically reserves each one that's returned. Models that can't be reserved (race condition) are filtered out.

Note: Because of race conditions, reserveFor()->limit(5) may return fewer than 5 results. If another process reserves a model between the query and the lock attempt, that model is excluded from the results.

Key types

Reservation keys can be strings, enums, or objects:

Multiple reservation types

A model can have multiple different reservation types simultaneously:

How it works

Reservable builds on Laravel's atomic cache locks, which use the cache_locks table to provide database-level mutual exclusion.

Lock key format

When you call $video->reserve('processing'), Reservable creates a cache lock with a specially formatted key:

For example: reservation:App\Models\Video:42:processing

Generated columns

The challenge with cache locks is that they're not inherently queryable by model. You can't efficiently ask "give me all Videos that aren't locked" because the lock table doesn't know about your models.

Reservable solves this by adding generated columns to the cache_locks table that parse the key format:

These columns are computed automatically by the database whenever a row is inserted or updated. The exact SQL varies by database engine (PostgreSQL uses split_part(), MySQL uses SUBSTRING_INDEX(), SQLite uses substr()).

Efficient queries

With generated columns in place, the reserved() and unreserved() scopes become simple JOIN queries:

This is much more efficient than fetching all videos and checking each lock individually in PHP.

Atomic reservations

The reserve() method uses Laravel's Lock::get() which performs an atomic database operation—either the lock is acquired or it isn't. There's no window where two processes can both think they have the lock.

The reserveFor scope combines this with query filtering: it finds unreserved models, then attempts to reserve each one, filtering out any that fail due to race conditions.

The CacheLock model

Reservable uses an Eloquent model (AaronFrancis\Reservable\Models\CacheLock) to query the cache_locks table. This model provides the reservations() relationship on your reservable models, allowing you to access active locks:

You can swap this for a custom model in the config if you need to add functionality.

Configuration

Testing

License

MIT