README

Description

Lockable Models provides short-lived edit locks for Eloquent models.

It is meant for collaborative backoffice flows where a record should be protected from concurrent edits while a user is working on it. The package offers a base lockable model, a base lock model, middleware that prevents actions on already locked models, and a terminate middleware that releases successful edit locks automatically.

Locks are user-aware, expire automatically after a configurable number of minutes, and allow the locking user to continue working on the same record while blocking everyone else.

The package depends on laravel-enso/users for lock ownership and display identity. It does not depend on people directly; the lock message uses the user model's public display API.

Installation

Install the package:

composer require laravel-enso/lockable-models

If needed, publish the config:

php artisan vendor:publish --tag=lockable-models-config

Default configuration:

return [
    'lock_duration' => 5,
];

To use the package, your implementation typically needs:

• a model extending LockableModel
• a related lock model extending ModelLock
• a one-to-one table for storing the current lock
• the request middleware pair on routes that edit the model

Features

• Creates user-specific temporary locks for editable models.
• Prevents concurrent actions when another user holds a non-expired lock.
• Allows the same user to continue editing an already locked model.
• Automatically expires stale locks after the configured duration.
• Releases locks automatically after successful requests.
• Provides reusable abstract models for both the lockable record and the lock record.

Usage

Create a lockable model by extending the base class:

use LaravelEnso\LockableModels\Models\LockableModel;

class Order extends LockableModel
{
}

Create a related lock model:

use LaravelEnso\LockableModels\Models\ModelLock;

class OrderLock extends ModelLock
{
}

Protect editing routes with the middleware pair:

Route::middleware([
    PreventActionOnLockedModels::class,
    UnlocksModelOnTerminate::class,
])->group(function () {
    // edit routes
});

Manually acquire and release a lock:

$order->lockFor($user);
$order->unlockFor($user);

::: warning Note UnlocksModelOnTerminate only releases locks when the response status is 200.

If a request fails or returns a different success status, the lock remains active until it is explicitly released or it expires. :::

API

Models

LaravelEnso\LockableModels\Models\LockableModel

Public methods:

• lock()
• lockFor(User $user): void
• unlockFor(User $user): void
• lockForMinutes(): int

LaravelEnso\LockableModels\Models\ModelLock

Public methods:

• expired(): bool
• allowed(User $user): bool
• user(): BelongsTo
• scopeIsExpired(Builder $query): Builder

Middleware

• PreventActionOnLockedModels
• UnlocksModelOnTerminate

Behavior:

• detects route parameters that are instances of LockableModel
• blocks the request if a valid lock belongs to another user
• acquires the lock for the current user before handling the request
• releases the lock on terminate for successful 200 responses

Exceptions

• LaravelEnso\LockableModels\Exceptions\ModelLockException

Current lock failure message:

• Locked by: :user

Depends On

Required Enso packages:

• laravel-enso/core ↗
• laravel-enso/helpers ↗
• laravel-enso/migrator ↗
• laravel-enso/users ↗

Framework dependency:

• laravel/framework ↗

Contributions

are welcome. Pull requests are great, but issues are good too.

Thank you to all the people who already contributed to Enso!