Eloquent Approval

Approval process for Laravel’s Eloquent models.

Why we need content approval in our apps

Unless you’re comfortable with unacceptable content, spam and any other
violations that may appear in what the users post, you need to include some
sort of content approval in your app.

Why approval process with three states

Although it’s possible to approve a model by using a boolean field but a field
that has three possible values: pending, approved and rejected gives us more
power. It differentiates between the models waiting for the decision and the
rejected ones and also makes it clear for the user if their content gets rejected.

How it works

After the setup, when new entities are being created, they are marked as
pending. Then their status can be changed to approved or rejected.

Also, when an update occurs that modifies attributes that require approval the
entity becomes suspended again.

By default the approval scope is applied on every query and filters out the
pending and rejected entities, so only approved entities are included.
You can include the entities that aren’t approved by explicitly specifying it.

Install

$ composer require mtvs/eloquent-approval

Setup

Registering the service provider

By default the service provider is registered automatically by Laravel package
discovery otherwise you need to register it in your config\app.php

Mtvs\EloquentApproval\ApprovalServiceProvider::class

Database

The following method adds two columns to the schema, one to store
the approval status named approval_status and another to store the timestamp at which the
last status update is occurred named approval_at.

$table->approvals()

You can change the default column names but then you need to specify them on the model too.

Model

Add Approvable trait to the model

use Illuminate\Database\Eloquent\Model;
use Mtvs\EloquentApproval\Approvable;
class Entity extends Model
{
    use Approvable;
}

If you want to change the default column names you need to specify them
by adding class constants to your model

use Illuminate\Database\Eloquent\Model;
use Mtvs\EloquentApproval\Approvable;
class Entity extends Model
{
    use Approvable;
    const APPROVAL_STATUS = 'custom_approval_status';
    const APPROVAL_AT = 'custom_approval_at';
}

Add approval_at to the model $dates list to get Carbon instances when accessing it.

Approval Required Attributes

When an update occurs that modifies attributes that require
approval, the entity becomes suspended again.

$entity->update($attributes); // an update with approval required modification
$entity->isPending(); // true

Note that this happens only when you perform the update on Model object
itself not by using a query Builder instance.

By default all attributes require approval.

/**
 * @return array
 */
public function approvalRequired()
{
    return ['*'];
}
/**
 * @return array
 */
public function approvalNotRequired()
{
    return [];
}

You can override them to have a custom set of approval required attributes.

They work like $fillable and $guarded in the Eloquent. approvalRequired() returns
the black list while approvalNotRequired() returns the white list.

Usage

Newly created entities are marked as pending and by default excluded from
queries on the model.

Entity::create(); // #1 pending
Entity::all(); // []
Entity::find(1); // null

Including all the entities

Entity::anyApprovalStatus()->get(); // retrieving all
Entity::anyApprovalStatus()->find(1); // retrieving one
Entity::anyApprovalStatus()->delete(); // deleting all

If you want to disable the approval scope totally on every query, you can set
the approvalScopeDisabled on the model.

use Illuminate\Database\Eloquent\Model;
use Mtvs\EloquentApproval\Approvable;
class Entity extends Model
{
    use Approvable;
    public $approvalScopeDisabled = true;
}

Limiting to only a specific status

Entity::onlyPending()->get(); // retrieving only pending entities
Entity::onlyRejected()->get(); // retrieving only rejected entities
Entity::onlyApproved()->get(); // retrieving only approved entities

Updating the status

On model objects

You can update the status of an entity by using provided methods on the Model
object.

$entity->approve(); // returns bool if the entity exists otherwise null  
$entity->reject(); // returns bool if the entity exists otherwise null  
$entity->suspend(); // returns bool if the entity exists otherwise null

On Builder objects

You can update the status of more than one entity by using provided methods on Builder
objects.

Entity::whereIn('id', $updateIds)->approve(); // returns number of updated
Entity::whereIn('id', $updateIds)->reject(); // returns number of updated
Entity::whereIn('id', $updateIds)->suspend(); // returns number of updated

Approval Timestamp

When you change the approval status of an entity its approval_at column updates.
Before the first approval action on an entity itsapproval_at is null.

Check the status of an entity

You can check the status of an entity using provided methods on Model objects.

$entity->isApproved(); // returns bool if entity exists otherwise null
$entity->isRejected(); // returns bool if entity exists otherwise null
$entity->isPending(); // returns bool if entity exists otherwise null

Approval Events

There are some model events that are dispatched before and after each approval action.

Also, there is a general event named approvalChanged that is dispatched whenever
the approval status is changed regardless of the actual status.

You can hook to them by calling the provided static methods, which are named
after them, and passing your callbacks. Or by registring observers with methods
with the same names.

use Illuminate\Database\Eloquent\Model;
use Mtvs\EloquentApproval\Approvable;
class Entity extends Model
{
    use Approvable;
    protected static function boot()
    {
        parent::boot();
        static::approving(function ($entity) {
            // You can halt the process by returning false
        });
        static::approved(function ($entity) {
            // $entity has been approved
        });
        // or:
        static::observe(ApprovalObserver::class);
    }
}
class ApprovalObserver
{
    public function approving($entity)
    {
        // You can halt the process by returning false
    }
    public function approved($entity)
    {
        // $entity has been approved
    }
}

Eloquent model events can also be mapped to your application event classes.

Duplicate Approvals

Trying to set the approval status to the current value is ignored, i.e.:
no event will be dispatched and the approval timestamp won’t be updated.
In this case the approval method returns false.

The Model Factory

Import the ApprovalFactoryStates to be able to use the approval states
when using the model factory.

    namespace Database\Factories;
    use Illuminate\Database\Eloquent\Factories\Factory;
    use Mtvs\EloquentApproval\ApprovalFactoryStates;
    class EntityFactory extends Factory
    {
        use ApprovalFactoryStates;
        public function definition()
        {
            //
        }
    }

    Entity::factory()->approved()->create();
    Entity::factory()->rejected()->create();
    Entity::factory()->suspended()->create();

Handling Approval HTTP Requests

You can import the HandlesApproval in a controller to perform the approval
operations on a model. It contains an abstract method which has to be implemented
to return the model’s class name.

    namespace App\Http\Controllers\Admin;
    use App\Http\Controllers\Controller;
    use App\Models\Entity;
    use Mtvs\EloquentApproval\HandlesApproval;
    class EntitiesController extends Controller
    {
        use HandlesApproval;
        protected function model()
        {
            return Entity::class;
        }
    }

The trait’s performApproval() does the approval and the request should be
routed to this method. It has the key and request parameters which are
passed to it by the router.

When do the routing, don’t forget to apply the auth and can middlewares for
authentication and authourization.

    Route::post(
        'admin/enitiy/{key}/approval', 
        'Admin\EntitiesController@performApproval'
    )->middleware(['auth', 'can:perform-approval'])

The request must have a approval_status key with
one of the possible values: approved, pending, rejected.

Frontend Components

There are also some UI components here written for Vue.js and Bootstrap that
you can use. First install them using the approval:ui artisan command and
then register them in your app.js file.

Approval Buttons Component

Call <approval-buttons> and pass the current-status and the approval-url
props to be able to make HTTP requests to set the approval status.

It emits the approval-changed event when an approval action happens.
The payload of the event is an object with the new approval_status and
approval_at values. Use the event to modify the corresponding keys on the
entity that in turn should change the current-status prop on the following
cycle.

Approval Status Component

Call <approval-status> and pass the value prop to show the current status.

Inspirations

When I was searching for an existing package for approval functionality
on eloquent models I encountered hootlex/laravel-moderation
even though I decided to write my own package I got some helpful inspirations from that one.

I also wrote different parts of the code following the way that similar parts
of Eloquent itself is written.