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.
You can install the package via composer:
composer require datomatic/laravel-enum-collections
The main parts of the package are:
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
)
You can make enum collection in 4 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);
from
method throw an ValueError
Exception if an element in $data
is wrong, instead tryFrom
skips bad data without raise exceptions.
$data
can be a single element or a collection
, array
,... of elements.
If $data
contains only Enum elements you can also omit the EnumClass
(the collection 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>
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
toValues
method serialize the collection content, if the element is a PureEnum
will be pass the name
of the case, otherwise 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]
You can cast a field to be an EnumCollection
.
To use this casting option, you need to set the Eloquent Model properly.
Schema::table('table', function (Blueprint $table) {
$table->json('field_name')->nullable()->after('some_field');
});
To set up your model you must:
- add a custom cast
AsLaravelEnumCollection::class
with the enumClass as attribute - add an optional
HasEnumCollections
trait to make query on enum collections fields
You can also cast more than one field if you need.
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),
];
}
}
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>
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
.
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
If you include also the HasEnumCollections
into the model, you can query the models with the new where functions whereContains
, orWhereContains
, whereDoesntContain
and orWhereDoesntContain
.
TestModel::whereContains('field_name', FieldEnum::PRIVATE)->get()
TestModel::whereDoesntContain('field_name', FieldEnum::PRIVATE)->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()
composer test
Please see CHANGELOG for more information on what has changed recently.
Please see CONTRIBUTING for details.
Please review our security policy on how to report security vulnerabilities.
The MIT License (MIT). Please see License File for more information.