README

Keepers for Laravel

Introduction

Larakeep is a package which allows to create and handle Keepers. Keepers allow to process the value of the desired model fields.

Sometimes, a field value must be configured when creating or updating a model instance. A common place to do this are the observers. This can lead to bloat the observers with repeated code or bloating the the models with functions, resulting in big files.

keepers allow to set the value of the desired fields on separate classes, keeping the code cleaner.

Actions VS Keepers

While Keepers and Actions share similarities, they serve different purposes in Laravel applications:

• Use Keepers when: You need to centralize computed fields, enforce model-based transformations, or derive values dynamically.
• Use Actions when: You are performing operations that modify multiple models, involve services, or handle workflow logic.

How to install Larakeep

Execute this command on the Laravel root project folder:

composer require edulazaro/larakeep

How to create a Keeper

You can create a Keeper manually or using the make command:

php artisan make:keeper MyModelKeeper

The Keeper will be created by default for the model \App\Models\MyModel.

You can also specify the model you are creating the Keeper for by using a second argument:

php artisan make:keeper MyClassKeeper  "\App\Models\Whatever\MyModel"

In this case, the keeper will be created for the model \App\Models\Whatever\MyModel.

How to configure a Keeper

After creating a Keeper, you will need to add the HasKeepers concern to the referenced model:

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use EduLazaro\Larakeep\Concerns\HasKeepers;

class MyModel extends Model
{
    use HasKeepers;
}

Registering Keepers manually

You can manually assign a Keeper to a model in a service provider's boot method:

namespace App\Providers;

use App\Models\MyModel;
use App\Keepers\MyModelKeeper;

class AppServiceProvider extends Model
{
    // ...
    public function boot()
    {
        // ...
        MyModel::keep(MyModelKeeper::class);
    }
}

You can add many Keepers to a single model:

MyModel::keep(MyModelKeeperA::class);
MyModel::keep(MyModelKeeperB::class);

Registering Keepers using Attributes

Alternatively, you can register Keepers using attributes directly in the model:

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use EduLazaro\Larakeep\Concerns\HasKeepers;
use EduLazaro\Larakeep\Attributes\KeptBy;
use App\Keepers\MyModelKeeper;

#[KeptBy(MyModelKeeper::class)]
class MyModel extends Model
{
    use HasKeepers;
}

This method allows you to keep the registration clean and self-contained within the model itself, without needing to modify the service provider.

Larakeep supports assigning multiple Keepers to a model using multiple #[KeptBy] attributes:

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use EduLazaro\Larakeep\Concerns\HasKeepers;
use EduLazaro\Larakeep\Attributes\KeptBy;
use App\Keepers\MyModelKeeperA;
use App\Keepers\MyModelKeeperB;

#[KeptBy(MyModelKeeperA::class)]
#[KeptBy(MyModelKeeperB::class)]
class MyModel extends Model
{
    use HasKeepers;
}

How to use a Keeper

To use Keeper you need to use the word get + the camel case version of the model attribute to process. For example, it's common to keep separate the model name and the search string for the model. In this case a keeper method is handy to set the attribute value:

namespace App\Keepers;

use \App\Models\MyClass;

class MyClassKeeper
{
    // ...
    public function getSearchText()
    {
        return $this->myClass->name . ' ' . $this->myClass->tag;
    }
}

The method can also accept parameters, adding the keyword With to the method name:

namespace App\Keepers;

use \App\Models\MyClass;

class MyClassKeeper
{
    // ...
    public function getSearchTextWith($whatever)
    {
        return $this->myClass->name . ' ' . $this->myClass->tag;
    }
}

Now, on an observer, you can process the search_text field to set its value:

$myClassInstance->process('search_text'); // To execute the getSearchText method.

Or if the method has parameters:

$myClassInstance->processWith('search_text', 'Any string'); // To execute the getSearchTextWith method.

You can also pass an array of fields to process all of them at the same time:

$myClassInstance->process(['search_text', 'word_count']);

The model will still need to be saved.

How to add Tasks

You can prepend any other word thanget to the keeper methods, like configure:

namespace App\Keepers;

use \App\Models\MyClass;

class MyClassKeeper
{
    // ...
    public function configureSearchText()
    {
        return $this->myClass->name . ' ' . $this->myClass->tag;
    }
}

However to process these fields with these methods you will need to use the processTask method:

$myClassInstance->processTaskWith('configure','search_text');

In the same way, these methods can also accept parameters:

namespace App\Keepers;

use \App\Models\MyClass;

class MyClassKeeper
{
    // ...
    public function configureSearchTextWith($whatever)
    {
        return $this->myClass->name . ' ' . $this->myClass->tag;
    }
}

The you would do:

$myClassInstance->processTaskWith('configure','search_text', 'Any string');

You can also pass an array of fields to process all of them at the same time:

$myClassInstance->processTask('configure', ['search_text', 'word_count']);

Saving data

The attributes will not be saved to the database. In order to do that, call the save method as usually:

$myClassInstance->process('configure')->save();

Sponsors

Larakeep is supported by the following sponsors. Thank you for keeping it growing:

 Kenodo      AndorraDev

Author

Created by Edu Lazaro

License

Larakeep is open-sourced software licensed under the MIT license.