https://github.com/testmonitor/eloquent-lockable
Make Laravel Eloquent models read-only after they're locked. Prevents updates and deletes based on a "locked" attribute.
https://github.com/testmonitor/eloquent-lockable
Last synced: about 2 months ago
JSON representation
Make Laravel Eloquent models read-only after they're locked. Prevents updates and deletes based on a "locked" attribute.
- Host: GitHub
- URL: https://github.com/testmonitor/eloquent-lockable
- Owner: testmonitor
- License: mit
- Created: 2025-04-17T14:40:44.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-10-28T15:29:49.000Z (6 months ago)
- Last Synced: 2025-12-27T06:03:36.538Z (4 months ago)
- Language: PHP
- Homepage: https://www.testmonitor.com/
- Size: 47.9 KB
- Stars: 1
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Eloquent Lockable
[](https://packagist.org/packages/testmonitor/eloquent-lockable)
[](https://circleci.com/gh/testmonitor/eloquent-lockable)
[](https://codecov.io/gh/testmonitor/eloquent-lockable)
[](https://styleci.io/repos/968120528)
[](https://packagist.org/packages/eloquent-lockable)
Make Laravel Eloquent models read-only after they're locked. Prevents updates and deletes based on a "locked" attribute. Includes a trait and required interface to clearly define and enforce lockable models.
## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [Tests](#tests)
- [Changelog](#changelog)
- [Contributing](#contributing)
- [Credits](#credits)
- [License](#license)
## Installation
This package can be installed through Composer:
```sh
$ composer require testmonitor/eloquent-lockable
```
No need to publish anything — just use the trait and you’re good to go.
## Usage
First, make sure to add a `locked` column to your model's table:
```php
Schema::table('invoices', function (Blueprint $table) {
$table->boolean('locked')->default(false);
});
```
Next, implement the Lockable trait and interface:
```php
use Illuminate\Database\Eloquent\Model;
use TestMonitor\Lockable\Traits\Lockable;
use TestMonitor\Lockable\Contracts\IsLockable;
class Invoice extends Model implements IsLockable
{
use Lockable;
}
```
That's it!
### Locking & Unlocking
Now you can start locking and unlocking models:
```php
$invoice->markLocked();
$invoice->markUnlocked();
$invoice->isLocked(); // true or false
```
### Exceptions
Trying to update or delete a locked model will throw a ModelLockedException.
```php
try {
$invoice->update(['amount' => 999]);
} catch (ModelLockedException $exception) {
$model = $exception->getModel();
}
```
### Temporary Locking
Temporarily lock or unlock a model using a callback:
```php
$invoice->whileLocked(function ($model) {
// Model is locked inside this closure
});
$invoice->whileUnlocked(function ($model) {
// Temporarily unlocked
});
```
These automatically restore the original lock state — even if an exception is thrown.
### Retrieving Locked and Unlocked Models
Convenient query scopes are provided to filter locked and unlocked models:
```php
Invoice::locked()->get();
Invoice::unlocked()->get();
```
These are local scopes and can be used just like any other Eloquent scope.
### Configurable Lock Column
Want to use a different column like archived or readonly?
Override the getLockColumn() method in your model:
```php
public function getLockColumn(): string
{
return 'archived';
}
```
### Allow Deletion of Locked Models
If you want to allow deletion of locked models, override the canDeleteWhenLocked() method in your model:
```php
public function canDeleteWhenLocked(): bool
{
return true;
}
```
### Allow Modifying Specific Attributes While Locked
Sometimes, you may want to allow certain attributes to be changed. To do this, override the getLockExceptions() method in your model:
```php
public function getLockExceptions(): array
{
return ['note'];
}
```
Only the attributes listed in getLockExceptions() may be modified while the model is locked.
## Tests
The package contains integration tests. You can run them using PHPUnit.
```
$ vendor/bin/phpunit
```
## Changelog
Refer to [CHANGELOG](CHANGELOG.md) for more information.
## Contributing
Refer to [CONTRIBUTING](CONTRIBUTING.md) for contributing details.
## Credits
- [Thijs Kok](https://www.testmonitor.com/)
- [Stephan Grootveld](https://www.testmonitor.com/)
- [Frank Keulen](https://www.testmonitor.com/)
- [All Contributors](../../contributors)
## License
The MIT License (MIT). Refer to the [License](LICENSE.md) for more information.