Stars: 131
Forks: 11
Pull Requests: 1
Issues: 13
Watchers: 5
Last Updated: 2023-02-18 07:26:45
Approval process for the Laravel`s Eloquent models 🟢🟡🔴
License: MIT License
Languages: PHP, Vue
Approval process for Laravel's Eloquent models.
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.
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.
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.
$ composer require mtvs/eloquent-approval
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
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.
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 getCarbon
instances when accessing it.
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 queryBuilder
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.
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
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;
}
Entity::onlyPending()->get(); // retrieving only pending entities
Entity::onlyRejected()->get(); // retrieving only rejected entities
Entity::onlyApproved()->get(); // retrieving only approved entities
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
Builder
objectsYou 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
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
.
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
There are some model events that are dispatched before and after each approval action.
Action | Before | After |
---|---|---|
approve | approving | approved |
suspend | suspending | suspended |
reject | rejecting | rejected |
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.
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
.
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();
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
.
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.
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.
Call <approval-status>
and pass the value
prop to show the current status.
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.