uteq/laravel-model-actions

Magically adds actions to a model

1.2.0 2021-03-19 14:46 UTC

Requires

• php: ^8.0
• illuminate/contracts: ^8.0
• spatie/laravel-package-tools: ^1.1

Requires (Dev)

• orchestra/testbench: ^6.0
• phpunit/phpunit: ^9.3
• spatie/laravel-ray: ^1.9
• vimeo/psalm: ^4.4

MIT

• Nathan Jansen

• uteq
• laravel-model-actions

README

This package will magically add actions to a model. Simply adding the WithActions trait:

Add the trait to your model

use Uteq\ModelActions\Concerns\WithActions;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    use WithActions;
}

And than use it in all sorts of ways:

$user->action()->update($input);
$user->action('update', $input);
$user->action(\App\Actions\User\Update::class, $input);

Whenever you need to call a method on a model that does not (yet) have an active record in the database, you can also use this static method.

User::do(Create::class, $input);

This package was inspired by this read about OOP: https://www.tonysm.com/when-objects-are-not-enough/#objects-in-the-large Especially the last part about actions being added to a model made sense to me. This will keep your models clean, and your actions separated.

The idea behind this package is that adding actions makes your application more scalable. 'Grouping' these actions by adding them to a model, makes it easier to comprehend where the action is for. It is more declarative having your model $user->action() perform an action than having the action out of the blue. To create more context you would have to always prefix your action UserCreateAction for example.

Not convinced about using Actions in your application? Read this excellent blog post of Brent from Spatie.be https://stitcher.io/blog/laravel-beyond-crud-03-actions

You will need php 8.0

Installation

You can install the package via composer:

composer require uteq/laravel-model-actions

You can publish the config file with:

php artisan vendor:publish --provider="Uteq\ModelActions\ModelActionsServiceProvider" --tag="laravel-model-actions-config"

This is the contents of the published config file:

return [
    /**
     * You can overwrite the method used to handle the
     * action. By default this is __invoke.
     */
    'method' => '__invoke',    
];

Usage

On your model

Add the WithActions trait to the model

use Uteq\ModelActions\Concerns\WithActions;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    use WithActions;
}

Directory

The actions should be added in the following folder structure

App
├── Actions
│   └── User
│       ├── Create.php 
│       ├── Update.php 
│       ├── Destroy.php
│       └── AddImage.php
└── Models
    └── User.php

After that you can always access the actions from your model:

This is how an action class looks like:

class Update
{
    public function __invoke(User $model, array $input = [])
    {
        // Now add you own logic here
    }
}

As you can see the $user will automatically be injected into the __invoke method. The system knows the user because you are calling in from the user. Please note that the model is always the first parameter.

The name of the Action class will be used as the method name. So a class UpdateImage will be accessible using User::action()->updateImage($input);

$user->action(Update::class, $input);

Dependency injection in Actions

Dependency injection in the __construct of the action is by default. So you can do this:

class Destroy
{
    public function __construct(
        protected PublicDestroyer $destroyer,
    ) { }
    
    public __invoke(User $user, array $input = [])
    {
        ($this->destroyer)($user, $input);
    }
}

Parameter binding

Parameter binding for model actions is pretty straight forward. We have Named parameters (see below) and simply using the given order:

class Action
{
    public function __invoke($var1, $var2)
    {
    
    }
}

User::do(Action::class, 'var1', 'var2');

Named parameters

Utilizing php 8's named paramters you are able to be very strict into what your action class accepts.

class Action
{
    public function __invoke($name)
    {
    
    }
}

User::do(Action::class, name: 'test');

Examples

Apply with actions to all your models

A convenient way to add the WithActions to all your Models is by simply extending the Eloquent Model class and extend upon that class.

namespace App\Support;

use Uteq\ModelActions\Concerns\WithActions;

class Model extends \Illuminate\Database\Eloquent\Model
{
    use WithActions;
}

class ActionModel extends \App\Support\Model
{

} 

Testing

composer test

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Nathan Jansen
• All Contributors

License

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