README

A package to add locking features to Eloquent Models.

Installation

You can install the package via composer:

composer require sfolador/laravel-locked

You can publish the config file with:

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

This is the contents of the published config file:

return [
   'locking_column' => 'locked_at',
   
    'default_namespace' => 'App\Models',

    'unlock_allowed' => true,
    'can_be_unlocked' => [
    ],
    
    'prevent_modifications_on_locked_objects' => false,
];

You can choose another default column name for the locking column by changing the locking_column value. The default_namespace value is used to automatically add the namespace to the model passed as an argument to the Command. See the Usage section for more details.

The unlock_allowed value is used to enable or disable the unlock command. If you set it to false, the unlock method will raise an exception. It's possible to add a whitelist of models that can be unlocked by setting the can_be_unlocked array. If the array is empty and the unlock_allowed value is false, no model can be unlocked.

The prevent_modifications_on_locked_objects value is used to forbid modifications on locked models. If you set it to true, an exception will be raised if you try to save/delete/replicated a locked model.

Command

There is an artisan command to create a migration for a class, run the command with :

php artisan lock-add {classname} {--namespace=}

For example, if you want to add a locking column to the User model, you can run the command :

php artisan lock-add User

This will create a migration file in the database/migrations folder, you can then run the migration with :

php artisan migrate

The command accepts an optional --namespace parameter, to specify the namespace of the class, for example :

php artisan lock-add User --namespace=App\Models\SomeFolder

The default namespace for the command is App\Models but you can change it in the config file by modifying the default_namespace value.

Usage

Once created the migration, you can use the Lockable trait in your model.

use Sfolador\Locked\Traits\HasLocks;

class User extends Model
{
    use HasLocks;
}

this trait will add the following methods to your model :

• lock() : adds a lock to the model by setting the locking column to the current date
• unlock(): removes the lock by setting the locking column to null
• isLocked(): returns true if the model is locked, false otherwise
• isUnlocked(): returns true if the model is unlocked, false otherwise
• isNotUnlocked(): returns true if the model is not unlocked, false otherwise
• isNotLocked(): returns true if the model is not locked, false otherwise
• toggleLock(): toggles the lock state of the model

Example

$user = User::find(1);
$user->lock();

//...

if ($user->isNotLocked()) {
   UserManager::update($user);
}

Todo

• Add an option to forbid locking a model if it is already locked and raise an Exception
• Add an option to block notifications to the model if it is locked
• Add logging to locking/unlocking actions for auditing purposes
• Add an option to block the model saving if it is locked

Testing

composer test

Changelog

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

Credits

• sfolador

License

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