README

This model allows for on-demand locking of models. You can integrate this with your permissions methodology of choice, or leave it stand-alone. This package allows you to determine whether a particular instance of a model is Locked or Not. Or it will independently prevent updating of a model instance.

Installation

Requires [PHP 7.3+ or 8.0+] and [Laravel 8.x or 9.x] (https://laravel.com/docs/8.x/releases or https://laravel.com/docs/9.x/releases)

You can install the package via composer:

composer require lowerrocklabs/laravel-lockable

You can publish and run the migrations with:

php artisan vendor:publish --tag="laravel-lockable-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --tag="laravel-lockable-config"

This is the contents of the published config file, which controls the global lock duration, this is customisable on a per-model basis (see below).

return [
    // Name of the Table containing the locks
    'locks_table' => 'model_locks',
    
     // Name of the Table containing the lock watchers
    'lock_watchers_table' => 'model_lock_watchers',
    
    // Enable retrieval of lock status on retrieving a model
    'get_locked_on_retrieve' => true,
    
    // Prevent updating if a model is locked by another user
    'prevent_updating' => true,

    // Time in Seconds For Lock To Persist
    'duration' => '3600',
];

Usage

Model Configuration

In the Model(s) that you wish to be lockable, add the IsLockable Trait

use LowerRockLabs\Lockable\Traits\IsLockable;

and then set the Trait

use IsLockable;

In Your Component/Controller

Then use the acquireLock function to attempt to acquire a lock on the model, it will return false if there is an existing lock.

acquireLock()

You can override the existing lock by calling the releaseLock() function before acquireLock(), if you are using a permissions-based approach, it is suggested that you restrict this to approriate users.

releaseLock()

You can tell if a lock exists as follows, this will acquire the lock if one does not exist.

isLocked()

You can send a Broadcast to the user holding the lock with the following

requestLock()

Lock Duration

You can override the default Lock Duration (in seconds) which is taken from the configuration on a per-model basis by setting the following in your Model, for example, the following would limit the duration of a lock to 600 seconds.

public $modelLockDuration = "600";

Locks will clear when the Duration has expired, and an attempt is made to access the Model, or you can call the commands below, or add them to a schedule (as you see fit).

Commands

To Flush Expired Locks

php artisan locks:flushexpired

To Flush All Locks

php artisan locks:flushall

Events

Two Events will be fired during the Lock process, that can be used to fire Notifications or Logs if desired On Model Locking

LowerRockLabs\Lockable\Events\ModelWasLocked;

and On Model UnLocking

LowerRockLabs\Lockable\Events\ModelWasUnLocked;

An additional event will be fired when a user requests the release of the lock and On Model UnLocking

LowerRockLabs\Lockable\Events\ModelUnlockRequested;

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

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

lowerrocklabs / laravel-lockable

Maintainers

Details