datomatic/laravel-enum-collections

A package to save a collection of Enums in a Eloquent field and interact with him

v3.2.1 2024-12-10 15:31 UTC

Requires

• php: ^8.1
• datomatic/laravel-enum-helper: ^2.0
• illuminate/contracts: ^9.0|^10.0|^11.0
• spatie/laravel-package-tools: ^1.13.0

Requires (Dev)

• laravel/pint: ^1.0
• nunomaduro/larastan: ^2.0.1
• orchestra/testbench: ^9.0
• pestphp/pest: ^1.0|^2.0|^3.0
• pestphp/pest-plugin-laravel: ^1.0|^2.0|^3.0
• phpstan/extension-installer: ^1.1
• phpstan/phpstan: ^1.10
• phpstan/phpstan-deprecation-rules: ^1.0
• phpstan/phpstan-phpunit: ^1.0
• phpunit/phpunit: ^9.0|^10.0|^11.0

MIT

• Alberto Peripolli

• laravel
• Datomatic
• laravel-enum-collections

README

Laravel Enum Collections

A Laravel collection extension to store enums with a useful eloquent field cast and a helper trait.
Take your interaction with enums to the next level.
Compatible with PureEnum, BackedEnum and datomatic/laravel-enum-helper package.

Installation

You can install the package via composer:

composer require datomatic/laravel-enum-collections

The main parts of the package are:

• EnumCollection
• Eloquent model casting
• HasEnumCollections trait

Using Laravel IDE Helper?

If you are using Laravel IDE Helper, you need to run the following command:

php artisan vendor:publish --tag="laravel-enum-collections-ide-helper-hooks"

and add LaravelEnumCollectionModelIdeHelperHook::class on model_hooks array in config/ide-helper.php

    'model_hooks' => [
        ...,
        LaravelEnumCollectionModelIdeHelperHook::class,
    ],

EnumCollection

EnumCollection is an extension of base Laravel collection that expand his functionalities to add the compatibility with:

• enum object instance
• enum case name string
• enum case value (only for BackedEnum)
• enum case (string) value (only for IntBackedEnum)

EnumCollection it's a one-dimensional collection that contains only enums.

Creating an EnumCollection

You can create an enum collection in four different ways:

use \Datomatic\EnumCollections\EnumCollection;

EnumCollection::of(Enum::class)->from($data);
EnumCollection::of(Enum::class)->tryFrom($data);
EnumCollection::from($data, Enum::class);
EnumCollection::tryFrom($data, Enum::class);
new EnumCollection($data, Enum::class);

The from method throws a ValueError exception if an element in $data is incorrect, whereas tryFrom skips invalid data without raising exceptions.
$data can be a single element or a collection, array, or other iterable of elements.

If $data contains only Enum elements, you can omit the EnumClass (the collection will take the EnumClass of the first element).

EnumCollection::from(Enum::CASE1); // ✅ EnumCollection<Enum::CASE1>
EnumCollection::from('CASE1', Enum::class); // ✅ EnumCollection<Enum::CASE1>
EnumCollection::from(1, Enum::class); // ✅ EnumCollection<Enum::CASE1>
EnumCollection::from('1', Enum::class); // ✅ EnumCollection<Enum::CASE1>
EnumCollection::from([Enum::CASE1,Enum::CASE2]); // ✅ EnumCollection<Enum>
EnumCollection::from(collect([Enum::CASE1,Enum::CASE2])); // ✅ EnumCollection<Enum>
new EnumCollection([Enum::CASE1,Enum::CASE2]); // ✅ EnumCollection<Enum>

Methods not supported by EnumCollection

range, median, mode, crossJoin, flip, collapse, collapseWithKeys, pluck, mergeRecursive, select, flatten, replaceRecursive, sliding, dot, undot, zip

Methods that return a normal Collection

map, keys, mapWithKeys, combine, mapToDictionary, groupBy, split, splitIn, chunk, chunkWhile, countBy, toBase

New methods

containsAny, doesntContainAny, toValues, toCollectionValues, mapStrict, mapWithKeysStrict

Contains method

use \Datomatic\EnumCollections\EnumCollection;

$enumCollection = EnumCollection::from([Enum::CASE1,Enum::CASE2]); // [1,2]

$enumCollection->contains(Enum::CASE1); // true
$enumCollection->contains(Enum::CASE3); // false
$enumCollection->doesntContain(Enum::CASE3); // true
$enumCollection->contains(1); // true
$enumCollection->contains('1'); // true
$enumCollection->contains('PRIVATE'); // true
$enumCollection->doesntContain('PRIVATE'); // false

ContainsAny method

use \Datomatic\EnumCollections\EnumCollection;

$enumCollection = EnumCollection::from([Enum::CASE1,Enum::CASE2]); // [1,2]

$enumCollection->containsAny([Enum::CASE1,Enum::CASE3]); // true
$enumCollection->doesntContainAny(['PRIVATE','PUBLIC']); // true

toValues method

The toValues method serializes the collection content. If the element is a PureEnum, it will return the name of the case; otherwise, it will return the value.

use \Datomatic\EnumCollections\EnumCollection;

EnumCollection::from([Enum::CASE1,Enum::CASE2,Enum::CASE2])->toValues(); // [1,2,2]
EnumCollection::from(['CASE1','CASE2','CASE2'],Enum::class)->toValues(); // [1,2,2]
EnumCollection::from([1,2,2],Enum::class)->toValues(); // [1,2,2]
EnumCollection::from(['1','2','2'],Enum::class)->toValues(); // [1,2,2]

Casting

You can cast a field to an EnumCollection. To use this casting option, you need to configure the Eloquent Model properly.

1. Database Migration

Schema::table('table', function (Blueprint $table) {
    $table->json('field_name')->nullable()->after('some_field');
});

2. Model Setup

To set up your model, you must:

• Add a custom cast AsLaravelEnumCollection::class with the enum class as an attribute.
• Optionally, add the HasEnumCollections trait to enable querying on enum collection fields.

You can cast multiple fields if needed.

use Datomatic\EnumCollections\Casts\AsLaravelEnumCollection;
use Datomatic\EnumCollections\EnumCollection;
use Illuminate\Database\Eloquent\Model;

class TestModel extends Model
{
    use HasEnumCollections;
    
    //Laravel 9/10
    protected $casts = [
        'field_name' => AsLaravelEnumCollection::class.':'.FieldEnum::class,
    ];
    
    //Laravel 11
    protected function casts(): array
    {
        return [
            'field_name' => AsLaravelEnumCollection::of(FieldEnum::class),
        ];
    }
}

Unique Modifier on Casting

When casting an enum collection field with the unique modifier, the collection will automatically filter out any duplicate values. This ensures that only unique values are stored in the model.

To use the unique modifier, you can set up your model as follows:

use Datomatic\EnumCollections\Casts\AsLaravelEnumCollection;
use Datomatic\EnumCollections\EnumCollection;
use Illuminate\Database\Eloquent\Model;

class TestModel extends Model
{
    use HasEnumCollections;
    
    // Laravel 9/10
    protected $casts = [
        'field_name' => AsLaravelEnumCollection::class.':'.FieldEnum::class.',true',
    ];
    
    // Laravel 11
    protected function casts(): array
    {
        return [
            'field_name' => AsLaravelEnumCollection::of(FieldEnum::class, true),
        ];
    }
}

Example Usage

When you set the enum collection field with repeated values, the duplicates will be removed:

$model = new TestModel();
$model->field_name = [FieldEnum::PRIVATE, FieldEnum::PUBLIC, FieldEnum::PRIVATE]; // ✅ EnumCollection<FieldEnum::PRIVATE, FieldEnum::PUBLIC>
$model->field_name = collect([FieldEnum::PRIVATE, FieldEnum::PUBLIC, FieldEnum::PRIVATE]); // ✅ EnumCollection<FieldEnum::PRIVATE, FieldEnum::PUBLIC>

Database Saved Data

The serialized enum collection saved in the database will contain only unique values, ensuring data integrity and preventing redundancy.

Interacting with Unique EnumCollection

You can interact with the field_name like a normal EnumCollection, but it will always contain unique values:

$model = new TestModel();
$model->field_name = [FieldEnum::PRIVATE, FieldEnum::PUBLIC, FieldEnum::PRIVATE];

$model->field_name->contains(FieldEnum::PRIVATE); // true
$model->field_name->contains(FieldEnum::PROTECTED); // false
$model->field_name->toValues(); // [1, 2]

Set the enum collection field

You can set enum collection field passing a single element, a collection or an array of elements. After the field will become an EnumCollection.

enum FieldEnum: int
{
    case PRIVATE = 1;
    case PUBLIC = 2;
    case PROTECTED = 3;
}

$model = new TestModel();
$model->field_name = FieldEnum::PRIVATE; // ✅ EnumCollection<FieldEnum::PRIVATE>
$model->field_name = 'PRIVATE'; // ✅ EnumCollection<FieldEnum::PRIVATE>
$model->field_name = 1; // ✅ EnumCollection<FieldEnum::PRIVATE>
$model->field_name = '1'; // ✅ EnumCollection<FieldEnum::PRIVATE>
$model->field_name = [FieldEnum::PRIVATE,FieldEnum::PUBLIC]; // ✅ EnumCollection<FieldEnum>
$model->field_name = collect([FieldEnum::PRIVATE,FieldEnum::PUBLIC]); // ✅ EnumCollection<FieldEnum>

Database saved data

A serialization of enumCollection is saved in the database, if the element is a PureEnum will be saved the name of the case, otherwise the value.

EnumCollection

Thanks to casting you can interact with field_name like a normal EnumCollection with all functionalities showed before.

$model = new TestModel();
$model->field_name = [FieldEnum::PRIVATE,FieldEnum::PUBLIC];

$model->field_name->contains(FieldEnum::PRIVATE); // true
$model->field_name->contains(FieldEnum::PROTECTED); // false
$model->field_name->contains(1); // true
$model->field_name->contains('1'); // true
$model->field_name->contains('PRIVATE'); // true
$model->field_name->doesntContain('PRIVATE'); // false
$model->field_name->doesntContain(FieldEnum::PROTECTED); // true

HasEnumCollections trait

If you include also the HasEnumCollections into the model, you can query the models with the new where functions whereContains, orWhereContains, whereDoesntContain, orWhereDoesntContain ,whereContainsAny, orWhereContainsAny, whereDoesntContainAny and orWhereDoesntContainAny.

TestModel::whereContains('field_name', FieldEnum::PRIVATE)->get()
TestModel::whereDoesntContain('field_name', FieldEnum::PRIVATE)->get()
TestModel::whereContainsAny('field_name', [FieldEnum::PRIVATE, FieldEnum::PUBLIC])->get()
TestModel::whereDoesntContainAny('field_name', [FieldEnum::PRIVATE, FieldEnum::PUBLIC])->get()


TestModel::whereContains('field_name', 1)
    ->whereContains('field_name', FieldEnum::PUBLIC)
    ->get()
    
TestModel::whereContains('field_name', [FieldEnum::PRIVATE,FieldEnum::PUBLIC])
    ->get()
TestModel::whereContains('field_name', collect([FieldEnum::PRIVATE,FieldEnum::PUBLIC]))
    ->get()
 TestModel::whereContains('field_name', EnumCollection::make([FieldEnum::PRIVATE,FieldEnum::PUBLIC]))
    ->get()
    
TestModel::whereContains('field_name', [1,2])
    ->get()

TestModel::whereContains('field_name', FieldEnum::PRIVATE)
    ->orWhereContains('field_name', FieldEnum::PUBLIC)
    ->get()

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

• Alberto Peripolli
• All Contributors

License

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