This package supercharges your PHP8 backed enums with superpowers like localization support and fluent comparison methods.
composer require webfox/laravel-backed-enumsCreating a new Laravel Backed Enum is easy with the make:enum command.
php artisan make:enum {name} --string # or --int{name}: The name of the enum class to be created (e.g., OrderStatus). The command will automatically append "Enum" to the name (e.g., OrderStatusEnum).{type?}: The underlying data type for the enum. Can be either --int --string or if not specified it will be a pure enum.{--force}: Overwrite the enum if it already exists. Example Usage:
To create an enum named OrderStatusEnum backed by integers:
php artisan make:enum OrderStatus --intTo create an enum named OrderStatusEnum backed by strings:
php artisan make:enum OrderStatus --stringTo create a pure enum named OrderStatusEnum:
php artisan make:enum OrderStatus
This will generate an OrderStatusEnums in the app/Enums directory.
The enum you create must implement the BackedEnum interface and also use the IsBackedEnum trait.
The interface is required for Laravel to cast your enum correctly and the trait is what gives your enum its superpowers.
use Webfox\LaravelBackedEnums\BackedEnum;
use Webfox\LaravelBackedEnums\IsBackedEnum;
enum VolumeUnitEnum: string implements BackedEnum
{
use IsBackedEnum;
case MILLIGRAMS = "milligrams";
case GRAMS = "grams";
case KILOGRAMS = "kilograms";
case TONNE = "tonne";
}Create enums.php lang file and create labels for your enum values.
// resources/lang/en/enums.php
return [
VolumeUnitEnum::class => [
VolumeUnitEnum::MILLIGRAMS->value => "mg",
VolumeUnitEnum::GRAMS->value => "g",
VolumeUnitEnum::KILOGRAMS->value => "kg",
VolumeUnitEnum::TONNE->value => "t"
]
];You may then access these localized values using the ->label() or ::labelFor() methods.
Additionally rendering the enum in a blade template will render the label.
VolumeUnitEnum::MILLIGRAMS->label(); // "mg"
VolumeUnitEnum::labelFor(VolumeUnitEnum::TONNE); // "t"
// in blade
{{ VolumeUnitEnum::KILOGRAMS }} // "kg"If you do not specify a label in the lang file these methods will return the value assigned to the enum inside the enum file. e.g MILLIGRAMS label will be milligrams.
Adding metadata allows you to return additional values alongside the label and values.
Create a withMeta method on your enum to add metadata.
public function withMeta(): array
{
return match ($this) {
self::MILLIGRAMS => [
'background_color' => 'bg-green-100',
'text_color' => 'text-green-800',
],
self::GRAMS => [
'background_color' => 'bg-red-100',
'text_color' => 'text-red-800',
],
self::KILOGRAMS, self::TONNE => [
'background_color' => 'bg-gray-100',
'text_color' => 'text-gray-800',
],
default => [
'background_color' => 'bg-blue-100',
'text_color' => 'text-blue-800',
],
};
}If you do not specify a withMeta method, meta will be an empty array.
Returns an array of all enum values with their labels and metadata.
VolumeUnitEnum::options();returns
[
[
'name' => 'MILLIGRAMS',
'value' => 'milligrams',
'label' => 'mg',
'meta' => [
'background_color' => 'bg-green-100',
'text_color' => 'text-green-800',
],
],
[
'name' => 'GRAMS',
'value' => 'grams',
'label' => 'g',
'meta' => [
'background_color' => 'bg-red-100',
'text_color' => 'text-red-800',
],
...
]
]Returns an array of all enum values.
VolumeUnitEnum::names();returns
[
'MILLIGRAMS',
'GRAMS',
'KILOGRAMS',
'TONNE',
]Returns an array of all enum values.
VolumeUnitEnum::values();returns
[
'milligrams',
'grams',
'killograms',
'tonne',
]Returns an array of all enum labels.
VolumeUnitEnum::labels();returns
[
'mg',
'g',
'kg',
't',
]Returns an array of all enum values mapping to their label.
VolumeUnitEnum::map();returns
[
'MILLIGRAMS' => 'mg',
'GRAMS' => 'g',
'KILOGRAMS' => 'kg',
'TONNE' => 't',
]Returns an array of a single enum value with its label and metadata.
VolumeUnitEnum::MILLIGRAMS->toArray();returns
[
'name' => 'MILLIGRAMS',
'value' => 'milligrams',
'label' => 'mg',
'meta' => [
'color' => 'bg-green-100',
'text_color' => 'text-green-800',
],
]An alias of ::label(). Used to satisfy Laravel's Htmlable interface.
VolumeUnitEnum::MILLIGRAMS->toHtml();returns
mgReturns a json string represention of the toArray return value.
Allows you to check if an enum is a given value. Returns a boolean.
Note
isA,isAnare just aliases foris.
VolumeUnitEnum::MILLIGRAMS->is(VolumeUnitEnum::MILLIGRAMS); //true
VolumeUnitEnum::MILLIGRAMS->is('MILLIGRAMS'); //true
VolumeUnitEnum::MILLIGRAMS->is('invalid'); //exceptionAllows you to check if an enum is not a given value. Returns a boolean.
Note
isNotAandisNotAnare just aliases forisNot.
VolumeUnitEnum::MILLIGRAMS->isNot(VolumeUnitEnum::GRAMS); //true
VolumeUnitEnum::MILLIGRAMS->isNot('GRAMS'); //true
VolumeUnitEnum::MILLIGRAMS->isNot('invalid'); //exceptionAllows you to check if an enum is contained in an array. Returns a boolean.
VolumeUnitEnum::MILLIGRAMS->isAny(['GRAMS', VolumeUnitEnum::TONNE]); // false
VolumeUnitEnum::MILLIGRAMS->isAny([VolumeUnitEnum::GRAMS, VolumeUnitEnum::MILLIGRAMS]); // trueAllows you to check if an enum is not contained in an array. Returns a boolean.
VolumeUnitEnum::MILLIGRAMS->isNotAny(['GRAMS', VolumeUnitEnum::TONNE]); // true
VolumeUnitEnum::MILLIGRAMS->isNotAny([VolumeUnitEnum::GRAMS, VolumeUnitEnum::MILLIGRAMS]); // falseThe backed enums may be validated using Laravel's standard Enum validation rule - new Illuminate\Validation\Rules\Enum(VolumeUnitEnum::class).
This method a shortcut for the validation rule.
public function rules(): array
{
return [
'volume_unit' => [VolumeUnitEnum::rule()],
];
}
This cast is similar to the Laravel built in AsEnumCollection cast but unlike the built-in will maintain the full toArray structure
when converting to json.
E.g. the Laravel built in AsEnumCollection cast will return the following json:
[
"MILLIGRAMS",
"GRAMS"
]This cast will return
[
{
"name": "MILLIGRAMS",
"value": "MILLIGRAMS",
"label": "mg",
"meta": {
"background_color": "bg-green-100",
"text_color": "text-green-800"
}
},
{
"name": "GRAMS",
"value": "GRAMS",
"label": "g",
"meta": {
"background_color": "bg-red-100",
"text_color": "text-red-800"
}
}
]Please see CHANGELOG for more information on what has changed recently.
We welcome all contributors to the project.
The MIT License (MIT). Please see License File for more information.