README

Easily add an approval process to any laravel model.

Description

Laravel Approvable is a package which helps when you have certain models in your application that should be editable by users, but the fields that they edit need to be approved first.

Installation

Via Composer

$ composer require victorlap/laravel-approvable

You can publish the migration with:

php artisan vendor:publish --provider="Victorlap\Approvable\ApprovableServiceProvider" --tag="migrations"
php artisan migrate

Setup

Assume you have a Post model. Each visitor on your site can edit any post, but before you want to publish the change to your website, you want to approve it first. By adding the \Victorlap\Approvable\Approvable trait to your Post model, when a visitor makes a change, a change request gets stored in the database. These changes can then later be applied, or denied by administrators. The currentUserCanApprove method can be used to determine who is authorized to make a change.

use Illuminate\Database\Eloquent\Model;
use Victorlap\Approvable\Approvable;

// Minimal
class Post extends Model
{
    use Approvable;   
}

// Extended
class Post extends Model
{
    use Approvable;

    protected $approveOf = array();

    protected $dontApproveOf = array();
    
    protected function currentUserCanApprove()
    {
        return Auth::check();
    }
    
    protected function getSystemUserId()
    {
        return Auth::id();
    }
}

Usage

Making a change to a model by a user who can approve does not change.

$post->title = "Very Good Post";
$post->save(); // This still works!

Making a change by an unauthorized user works the same.

$post->title = "Very Good Post";
$post->save(); // Post remains with the old title in the database, however a change request is now also present.

You can retrieve a list of attributes that have pending changes by using

$post->getPendingApprovalAttributes();

Or check if a certain attribute has pending changes

$post->isPendingApproval('title');

Scopes have been defined to quickly see approvals in different states. For example if you wnat to show administrators a list with changes that can be accepted you can use the open scope. Other scopes are accepted, rejected and ofClass.

Approval::open()->get();
Approval::accepted()->get();
Approval::rejected()->get();
Approval::ofClass(Post::class)->get();

You can combine the scopes of course, or use them in combination with regular query builder methods

Approval::open()->ofClass(Post::class)->get();

Accepting and rejecting of approvals can be done using the accept and reject methods on the Approval.

$approvals = Post::find(1)->approvals()->open()->get();
$approvals->each->accept(); // or
$approvals->each->reject();

If you dont want a model to pass approval, you can use the withoutApproval() method.

// Now this post model is not checked for changes.
$post->withoutApproval()
      ->fill([
        'title' => 'A new title',
      ])
      ->save();

To re-enable the approval for this model instance, you can use the withApproval() method.

Limitations

Currently Approvable does not handle creation of models, PR's are welcome for this.

Change log

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

Testing

$ composer test

Contributing

Please see CONTRIBUTING and CONDUCT for details.

Security

If you discover any security related issues, please email victorlap@outlook.com instead of using the issue tracker.

Credits

License

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

victorlap / laravel-approvable

Maintainers

Details