narcisonunez/laravel-actionable-model

Allow actions in your laravel model

1.3.2 2021-04-10 15:02 UTC

This package is auto-updated.

Last update: 2022-06-10 17:42:14 UTC


README

Latest Version on Packagist GitHub Tests Action Status GitHub Code Style Action Status Total Downloads

Allow models to perform or receive actions.

Installation

You can install the package via composer:

composer require narcisonunez/laravel-actionable-model

You can publish and run the migrations with:

php artisan vendor:publish --provider="Narcisonunez\LaravelActionableModel\LaravelActionableModelServiceProvider" --tag="actionable-model-migrations"
php artisan migrate

Basic Setup

Register your actions

Add your action in your AppServiceProvider

use Narcisonunez\LaravelActionableModel\Facades\ActionableActionTypes;
use App\ActionTypes\KudosActionType;

ActionableActionTypes::register([
    'like',
    'kudos' => KudosActionType::class,
    'celebrate'
]);

You can implement your own class extending ActionableTypeRecord to add more logic to your records.
Ex. icon method to get that specific action type icon. Now, Any kudos action will have a method named icon.

Your actions will be used as dynamic method calls. See below.

Create a new Actionable Action Type (OPTIONAL)

php artisan actionable:type LikeActionType

Add aliases to your models (OPTIONAL)

Add your aliases in your AppServiceProvider

use App\Models\Cause;
use App\Models\User;
use Narcisonunez\LaravelActionableModel\Facades\ActionableModelAliases;

ActionableModelAliases::register([
    User::class => 'user',
    Cause::class => 'cause'
]);

Storing aliases in the database will prevent losing the reference if you move your models to another directory.

Update existing models references to use the new alias

In case you already have data in the database, after adding the aliases you can run:

php artisan actionable:update-aliases // Update all the records

If you want just to update a specific value

php artisan actionable:update-aliases --from="App\\User" --to="App\\Models\\User"

To update all your existing records.

Traits

A model that can perform actions you need to include:

// Imports 
class User extends Authenticatable
{
    use ActionableModel;
    use CanPerformActions;
    ...
}

The model that can receive the actions must implement CanBeActionable

...
use Narcisonunez\LaravelActionableModel\Traits\ActionableModel;

class Cause extends Model implements CanBeActionable
{
    use ActionableModel;
    ...
}

Basic Usage

Perform an action

// You will use your actions as methods call.
$user->performActionOn($cause)->like();
$user->performActionOn($cause)->kudos();
$user->performActionOn($cause)->celebrate();

Check if the action was already made

// returns False or an ActionableTypeRecord
$user->hasPerformedAction('like')->on($cause);

Toggle your actions

// remove if exists the action, otherwise creates a new like
$user->performActionOn($cause)->toggle('like');
// OR
// toggleACTIONTYPE
$user->performActionOn($cause)->toggleLike(); 
$user->performActionOn($cause)->toggleKudos(); 
$user->performActionOn($cause)->toggleCelebrate(); 

Manually delete an action (See Toggle above)

if ($action  = $user->hasPerformedAction('like')->on($cause) ) {
    $action->delete();
}

Get all the actions

$user->actions;

// To help you out filtering your actions. You can use the actionsFilter method
$user->actionsFilter()->get();
$user->actionsFilter()->latest(10);
$user->actionsFilter()->given()->get();
$user->actionsFilter()->received()->get();
$user->actionsFilter()->ofType('like')->get();
$cause->actionsFilter()->by($user)->ofType('like')->get();
$cause->actionsFilter()->by($user)->ofType('like')->count();

- Available methods -

Method Description
get Returns a collection of ActionableTypeRecord
count Returns the number of records
given Filters all the records where the current model performed the actions
received Filters all the records where the current model received the actions
ofType Filters by the actionType
by Filters all the actions in the current model where the model passed to this method performed the action
latest Get the collection sorted by the latest ones.

Actionable Record

The methods above will return a collection of ActionableRecord.
The access the owner or the actionable models, you can do it like this:

$actionRecord = $user->actionsFilter()->ofType('like')->get()->first();

$actionRecord->owner; // The model that performed the action
$actionRecord->actionable; // The model that received the action
$actionRecord->action; // Action that was performed. ex. like, kudos, celebrate, etc.
$actionRecord->type; // An alias to action

💖 Support the development

Do you like this project? Support it by donating

License

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