22# Laravel Enum Collections
33
44[ ![ Latest Version on Packagist] ( https://img.shields.io/packagist/v/datomatic/laravel-enum-collections.svg?style=for-the-badge )] ( https://packagist.org/packages/datomatic/laravel-enum-collections )
5- [](https://github.com/datomatic/laravel-enum-collections/tree/main/tests)
6- [](https://github.com/datomatic/laravel-enum-collections/actions/workflows/run-tests.yml)
7- [ ![ GitHub Code Style Action Status] ( https://img.shields.io/github/actions/workflow/status/datomatic/laravel-enum-collections/phpstan.yml?label=code%20style&color=5FE8B3 &style=for-the-badge )] ( https://github.com/datomatic/laravel-enum-collections/actions/workflows/fix-php-code-style-issues.yml )
5+ [](https://github.com/datomatic/laravel-enum-collections/tree/main/tests)
6+ [](https://github.com/datomatic/laravel-enum-collections/actions/workflows/run-tests.yml)
7+ [ ![ GitHub Code Style Action Status] ( https://img.shields.io/github/actions/workflow/status/datomatic/laravel-enum-collections/phpstan.yml?label=code%20style&color=7DDFA8 &style=for-the-badge )] ( https://github.com/datomatic/laravel-enum-collections/actions/workflows/fix-php-code-style-issues.yml )
88[ ![ Total Downloads] ( https://img.shields.io/packagist/dt/datomatic/laravel-enum-collections.svg?style=for-the-badge )] ( https://packagist.org/packages/datomatic/laravel-enum-collections )
99
10- Save a collection of Enums in an Eloquent field and interact with it.
10+ A Laravel Collection extension to store enums with a useful eloquent fields cast.
11+ Take your interaction with enums to the next level.
1112Compatible with ` PureEnum ` , ` BackedEnum ` and [ ` datomatic/laravel-enum-helper ` ] ( https://github.com/datomatic/laravel-enum-helper ) package.
1213
1314## Installation
@@ -18,9 +19,69 @@ You can install the package via composer:
1819composer require datomatic/laravel-enum-collections
1920```
2021
21- ## Set up
22+ ## EnumCollection
2223
23- Before you can use this package you must setup the eloquent Model.
24+ ` EnumCollection ` is an extension of base [ Laravel collection] ( https://laravel.com/docs/collections ) that expand his functionalities and overload the ` contains ` method to add the compatibility with:
25+ - enum object instance
26+ - enum case name string
27+ - enum case value (only for ` BackedEnum ` )
28+ - enum case (string) value (only for ` IntBackedEnum ` )
29+
30+ ### Creating an EnumCollection
31+
32+ You can set enum collection field passing in 4 ways:
33+ ``` php
34+ use \Datomatic\EnumCollections\EnumCollection;
35+
36+ EnumCollection::of(Enum::class)->from($data);
37+ EnumCollection::of(Enum::class)->tryFrom($data);
38+ EnumCollection::from($data, Enum::class);
39+ EnumCollection::tryFrom($data, Enum::class);
40+ ```
41+ ` from ` method throw an ` ValueError ` Exception if an element in ` $data ` is wrong, instead ` tryFrom ` skips bad data without raise exceptions.
42+ ` $data ` can be a single element or a ` collection ` , ` array ` ,... of elements.
43+
44+ If ` $data ` contains only Enum elements you can also omit the ` EnumClass ` (the collection take the EnumClass of the first element).
45+ ``` php
46+ EnumCollection::from(Enum::CASE1); // ✅ EnumCollection<Enum::CASE1 >
47+ EnumCollection::from('CASE1', Enum::class); // ✅ EnumCollection<Enum::CASE1 >
48+ EnumCollection::from(1, Enum::class); // ✅ EnumCollection<Enum::CASE1 >
49+ EnumCollection::from('1', Enum::class); // ✅ EnumCollection<Enum::CASE1 >
50+ EnumCollection::from([Enum::CASE1,Enum::CASE2]); // ✅ EnumCollection<Enum >
51+ EnumCollection::from(collect([Enum::CASE1,Enum::CASE2])); // ✅ EnumCollection<Enum >
52+ ```
53+
54+ ### `Contains' method
55+
56+ ``` php
57+ use \Datomatic\EnumCollections\EnumCollection;
58+
59+ $enumCollection = EnumCollection::from([Enum::CASE1,Enum::CASE2]); // [1,2]
60+
61+ $enumCollection->contains(Enum::CASE1); // true
62+ $enumCollection->contains(Enum::CASE3); // false
63+ $enumCollection->doesntContain(Enum::CASE3); // true
64+ $enumCollection->contains(1); // true
65+ $enumCollection->contains('1'); // true
66+ $enumCollection->contains('PRIVATE'); // true
67+ $enumCollection->doesntContain('PRIVATE'); // false
68+ ```
69+
70+ ### `toValues' method
71+ ` toValues ` method serialize the collection content, if the element is a ` PureEnum ` will be pass the ` name ` of the case, otherwise the ` value ` .
72+
73+ ``` php
74+ use \Datomatic\EnumCollections\EnumCollection;
75+
76+ EnumCollection::from([Enum::CASE1,Enum::CASE2,Enum::CASE2])->toValues(); // [1,2,2]
77+ EnumCollection::from(['CASE1','CASE2','CASE2'],Enum::class)->toValues(); // [1,2,2]
78+ EnumCollection::from([1,2,2],Enum::class)->toValues(); // [1,2,2]
79+ EnumCollection::from(['1','2','2'],Enum::class)->toValues(); // [1,2,2]
80+ ```
81+
82+ ## Casting
83+
84+ Before you can use this casting option you must config the eloquent Model.
2485
2586### 1. Database Migration
2687``` php
@@ -32,48 +93,41 @@ Schema::table('table', function (Blueprint $table) {
3293### 2. Model set up
3394
3495To set up your model you must:
35- - add a custom cast ` EnumCollections::class `
36- - add an ` $enumCollections ` array containing the fields and relative enum classes
96+ - add a custom cast ` AsEnumCollections::class ` with the enumClass as attribute
3797- add an optional ` HasEnumCollections ` trait to make query on enum collections fields
3898
3999You can also set more than one field if you need.
40100
41101``` php
42102
43- use Datomatic\EnumCollections\Casts\EnumCollections ;
103+ use Datomatic\EnumCollections\Casts\AsEnumCollection ;
44104use Datomatic\EnumCollections\EnumCollection;
45105use Illuminate\Database\Eloquent\Model;
46106
47107class TestModel extends Model
48108{
49109 use HasEnumCollections;
50110
111+ //Laravel 9/10
51112 protected $casts = [
52- 'field_name' => EnumCollections ::class,
113+ 'field_name' => AsEnumCollection::class.':'.FieldEnum ::class,
53114 ];
54115
55- public array $enumCollections = [
56- 'field_name' => FieldEnum::class,
57- ];
116+ //Laravel 11
117+ protected function casts(): array
118+ {
119+ return [
120+ 'field_name' => AsEnumCollection::of(FieldEnum::class),
121+ ];
122+ }
58123}
59124```
60125
61- ## Usage
62-
63- After model set up you can use the package potentials.
64-
65-
66126### Set the enum collection field
67127
68128You can set enum collection field passing a single element, a collection or an array of elements.
69129After the setting, the field will become an ` EnumCollection ` .
70130
71- Each element can be an:
72- - enum object instance
73- - enum case name string
74- - enum case value (only for ` BackedEnum ` )
75- - enum case (string) value (only for ` IntBackedEnum ` )
76-
77131``` php
78132enum FieldEnum: int
79133{
@@ -91,12 +145,11 @@ $model->field_name = [FieldEnum::PRIVATE,FieldEnum::PUBLIC]; // ✅ EnumCollecti
91145$model->field_name = collect([FieldEnum::PRIVATE,FieldEnum::PUBLIC]); // ✅ EnumCollection<FieldEnum >
92146```
93147
148+ ### Database saved data
149+ 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 ` .
150+
94151### EnumCollection
95- The ` EnumCollection ` extend the [ Laravel collection] ( https://laravel.com/docs/collections ) and overload the ` contains ` method to add the compatibility with:
96- - enum object instance
97- - enum case name string
98- - enum case value (only for ` BackedEnum ` )
99- - enum case (string) value (only for ` IntBackedEnum ` )
152+ Thanks to casting you can interact with ` field_name ` like a normal ` EnumCollection ` with all functionalities showed before.
100153
101154``` php
102155
@@ -108,6 +161,8 @@ $model->field_name->contains(FieldEnum::PROTECTED); // false
108161$model->field_name->contains(1); // true
109162$model->field_name->contains('1'); // true
110163$model->field_name->contains('PRIVATE'); // true
164+ $model->field_name->doesntContain('PRIVATE'); // false
165+ $model->field_name->doesntContain(FieldEnum::PROTECTED); // true
111166```
112167
113168### HasEnumCollections trait
0 commit comments