Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/victorlap/laravel-approvable

Easily add an approval process to any laravel model.
https://github.com/victorlap/laravel-approvable

approvable approval approval-process eloquent hacktoberfest laravel

Last synced: 3 months ago
JSON representation

Easily add an approval process to any laravel model.

Awesome Lists containing this project

README 

        
# Laravel Approvable



[![Latest Version on Packagist][ico-version]][link-packagist]

[![Software License][ico-license]](LICENSE.md)

[![Build Status][ico-travis]][link-travis]

[![Coverage Status][ico-scrutinizer]][link-scrutinizer]

[![Quality Score][ico-code-quality]][link-code-quality]

[![StyleCI](https://styleci.io/repos/80375034/shield?branch=master)](https://styleci.io/repos/80375034)

[![Total Downloads][ico-downloads]][link-downloads]



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



``` bash

$ composer require victorlap/laravel-approvable

```



You can publish the migration with:

```bash

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.



```php

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.

```php

$post->title = "Very Good Post";

$post->save(); // This still works!

```



Making a change by an unauthorized user works the same.

```php

$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

```php

$post->getPendingApprovalAttributes();

```



Or check if a certain attribute has pending changes

```php

$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`.

```php

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

```php

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

```



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

```php

$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.

```php

// 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](CHANGELOG.md) for more information on what has changed recently.



## Testing



``` bash

$ composer test

```



## Contributing



Please see [CONTRIBUTING](CONTRIBUTING.md) and [CONDUCT](CONDUCT.md) for details.



## Security



If you discover any security related issues, please email [email protected] instead of using the issue tracker.



## Credits



- [Victor Lap][link-author]

- [All Contributors][link-contributors]



## License



The MIT License (MIT). Please see [License File](LICENSE.md) for more information.



[ico-version]: https://img.shields.io/packagist/v/victorlap/laravel-approvable.svg?style=flat-square

[ico-license]: https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square

[ico-travis]: https://img.shields.io/travis/victorlap/laravel-approvable/master.svg?style=flat-square

[ico-scrutinizer]: https://img.shields.io/scrutinizer/coverage/g/victorlap/laravel-approvable.svg?style=flat-square

[ico-code-quality]: https://img.shields.io/scrutinizer/g/victorlap/laravel-approvable.svg?style=flat-square

[ico-downloads]: https://img.shields.io/packagist/dt/victorlap/laravel-approvable.svg?style=flat-square



[link-packagist]: https://packagist.org/packages/victorlap/laravel-approvable

[link-travis]: https://travis-ci.org/victorlap/laravel-approvable

[link-scrutinizer]: https://scrutinizer-ci.com/g/victorlap/laravel-approvable/code-structure

[link-code-quality]: https://scrutinizer-ci.com/g/victorlap/laravel-approvable

[link-downloads]: https://packagist.org/packages/victorlap/laravel-approvable

[link-author]: https://github.com/victorlap

[link-contributors]: ../../contributors