datomatic / laravel-enum-helper
Simple opinionated framework agnostic PHP 8.1 enum helper for Laravel
Installs: 119 596
Dependents: 3
Suggesters: 0
Security: 0
Stars: 30
Watchers: 2
Forks: 3
Open Issues: 0
Requires
- php: ^8.1
- composer/class-map-generator: ^1.0
- datomatic/enum-helper: ^2.0
- illuminate/support: ^8.0|^9.0|^10.0|^11.0
- illuminate/translation: ^8.0|^9.0|^10.0|^11.0
- jawira/case-converter: ^3.5
- laminas/laminas-code: ^4.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.8
- laravel/pint: ^1.18
- nunomaduro/larastan: ^2.0
- orchestra/testbench: ^6.23|^7.0|^8.0|^9.0
- pestphp/pest: ^1.0|^2.0|^3.0
- pestphp/pest-plugin-laravel: ^1.0|^2.0|^3.0
- phpstan/phpstan: ^1.7
README
Laravel Enum Helper
This is an extension of the datomatic/enum-helper package based on Laravel Framework.
The package consists on a LaravelEnumHelper trait that extends EnumInvokable, EnumFroms, EnumNames,
EnumValues, EnumEquality, EnumDescription and add dynamic methods to return a translation or "property" method and
relative helper methods.
You can think about it as an EnumDescription trait but completely dynamic.
So you can define a custom method() and have these functions available: [method]s(), [method]sByName(),
[method]sByValue(). For example with color() you obtain colors(), colorsByName(), colorsByValue() methods.
The cool thing is you can also avoid writing the method and write only the translations.
For example, you can define the property excerpt by writing only the translations on enums.php (see below for explanation)
and obtain excerpt(), excerpts(), excerptsByName(), excerptsByValue() methods.
The package use the Laravel Pluralizer component to get the singular method to call or to translate.
Related Packages
- datomatic/laravel-enum-collections if you need to save and interact many enum values on one field.
- datomatic/nova-enum-field if you are using Laravel Nova, this package adds the PHP 8.1
enum,EnumDescriptionandLaravelEnumHelpertraits support, with a Nova Select and Nova Boolean filters ready out of the box.
The enum-helper base package summary
You should see the datomatic/enum-helper details on his repository, this is a summary:
- Invokable cases: get the value of enum "invoking" it statically
- Construct enum by name or value:
from(),tryFrom(),fromName(),tryFromName()for all enums - Enums Inspection:
isPure(),isBacked(),has(),hasName(),hasValue()methods - Enums Equality:
is(),isNot(),in(),notIn()methods - Names: methods to have a list of case names (
names(),namesByValue()) - Values: methods to have a list of case values (
values(),valuesByName()) - Unique ID: get an unique identifier from instance or instance from identifier (
uniqueId(),fromUniqueId()) - Descriptions & Translations: add description to enum with optional translation (
description(),descriptions(),descriptionsByName(),descriptionsByValue())
Installation
Laravel 8 or above and PHP 8.1+ are required.
composer require datomatic/laravel-enum-helper
Usage
You can use this functionality simply using the LaravelEnumHelper trait.
use Datomatic\LaravelEnumHelper\LaravelEnumHelper; // Pure enum enum Status { use LaravelEnumHelper; case PENDING; case ACCEPTED; case DISCARDED; case NO_RESPONSE; public function color(): string { return match ($this) { self::PENDING => '#000000', self::ACCEPTED => '#0000FF', self::DISCARDED => '#FF0000', self::NO_RESPONSE => '#FFFFFF', }; } } // BackedEnum enum StatusString { use LaravelEnumHelper; case PENDING = 'P'; case ACCEPTED = 'A'; case DISCARDED = 'D'; case NO_RESPONSE = 'N'; // or public function color(?string $lang = null): string public function color(): string { ... }
After that you can define a custom "property" method like color() or color(?string $lang = null) or define the translations instead.
Annotation command
A convenient command is available to generate DocBlock annotations for enum classes.
php artisan enum:annotate {class?} {--folder=}
# Single enum
php artisan enum:annotate "Enums\FQN\ClassName"
# All enums in a folder
php artisan enum:annotate --folder=Enums/Folder/Path
This command generate the phpDoc annotations for invokable case methods.
Translations
Using this trait there is 2 way to manage translation strings.
Using Short Keys
Language strings may be stored in enums.php files within the lang directory. Within this directory, there may be subdirectories for each language supported by the application.
/lang
/en
enums.php
/it
enums.php
All language files return an array of keyed strings. The array has 3 levels:
- first level key: the complete class name of the enum
- second level key: the name of the property to translate
- third level key: the name/value of the enum case.
The default property is description so if you use only that property you can use just a 2 level array.
// /lang/it/enums.php return [ // If you need to translate just the description property Status::class => [ Status::PENDING() => 'In attesa', // using invokable trait functionality 'ACCEPTED' => 'Accettato', // using the name of pure enum case 'DISCARDED' => 'Rifiutato', 'NO_RESPONSE' => 'Nessuna Risposta', ], // If you need to translate multiple properties (e.g. description, excerpt) StatusString::class => [ 'description' => [ // using invokable trait functionality StatusString::PENDING() => 'In attesa', StatusString::ACCEPTED() => 'Accettato', ... ], 'excerpt' => [ // using the value of BackedEnum case "P" => 'In attesa', "A" => 'Accettato', ...
Using Translation Strings As Keys
Language strings are stored as JSON files in the lang directory (e.g. lang/it.json).
In this example the description property is translated:
{
"enums.Namespace\\StatusString.description.P": "In attesa",
"...":"..."
}
But if you want to use this way, you can simply define the method on Enum class like this description method.
public function description(?string $lang = null): string { return match ($this) { self::PENDING => __('Await decision', $lang), self::ACCEPTED => __('Recognized valid', $lang), self::DISCARDED => __('No longer useful', $lang), self::NO_RESPONSE => __('No response', $lang), };
[property]() method
This dynamic method try to resolve property() method on the enum.
If the method not exist try to translate the instance value with the framework translation function
__("enums.Namespace\EnumClass.property.CASE_NAME").
Because the default property is description, if there isn't a translation to that property there is a fallback that takes the case name humanized.
With the other properties, if the translation does not exist, the package throws a TranslationMissing exception.
static [property]s() method
This dynamic method gets a list of case property() returns of the enum.
The name of the method is the plural of the property so if you are using property it will be properties().
StatusString::descriptions(); // ['Await decision','Recognized valid','No longer useful','No response'] StatusString::colors(); // ['#000000','#0000FF','#FF0000','#FFFFFF'] // Subset StatusString::descriptions([StatusString::ACCEPTED, StatusString::NO_RESPONSE]); // ['Recognized valid','No response'] StatusString::colors([StatusString::ACCEPTED, StatusString::NO_RESPONSE]); // ['#0000FF','#FFFFFF'] // Forcing language Status::descriptions(null, 'it'); // 🇮🇹 ['In attesa','Accettato','Rifiutato','Nessuna Risposta'] StatusString::colors(null, 'it'); // ['#000000','#0000FF','#FF0000','#FFFFFF'] // Subset and language Status::descriptions([Status::NO_RESPONSE, Status::DISCARDED], 'it'); // 🇮🇹 ['Nessuna Risposta', 'Rifiutato'] StatusString::colors([StatusString::ACCEPTED, StatusString::NO_RESPONSE], 'it'); // ['#0000FF','#FFFFFF']
static [property]sByName() method
This dynamic method returns an associative array of [case name => property() result].
The name of the method is the plural of the property so if you are using property it will be propertiesByName().
StatusString::descriptionsByName(); // ['PENDING' => 'Await decision', 'ACCEPTED' => 'Recognized valid',... StatusString::colorsByName(); // ['PENDING' => '#000000','ACCEPTED' => '#0000FF',... Status::descriptionsByName(); // ['PENDING' => 'Await decision', 'ACCEPTED' => 'Recognized valid',... // Subset StatusString::descriptionsByName([StatusString::DISCARDED, StatusString::ACCEPTED]); // ['DISCARDED' => 'No longer useful', 'ACCEPTED' => 'Recognized valid'] Status::descriptionsByName([Status::PENDING, Status::DISCARDED]); // ['PENDING' => 'Await decision', 'DISCARDED' => 'No longer useful'] // Forcing language StatusString::descriptionsByName(null, 'it'); // 🇮🇹 ['P' => 'In attesa','A' => 'Accettato',... // Subset and language Status::descriptionsByName([Status::DISCARDED, Status::NO_RESPONSE], 'it'); // 🇮🇹 ['DISCARDED' => 'Rifiutato','NO_RESPONSE' => 'Nessuna Risposta',...
static [property]sByValue() method
This dynamic method returns an associative array of [case value => property() result] on BackedEnum, [case name => property() result] otherwise.
The name of the method is the plural of the property so if you are using property it will be propertiesByValue().
Status::descriptionsByValue(); // ['PENDING' => 'Await decision', 'ACCEPTED' => 'Recognized valid',... StatusString::descriptionsByValue(); // ['P' => 'Await decision', 'A' => 'Recognized valid',... StatusString::colorsByValue(); // ['P' => '#000000','A' => '#0000FF',... // Subset Status::descriptionsByValue([Status::PENDING, Status::DISCARDED]); // ['PENDING' => 'Await decision', 'DISCARDED' => 'No longer useful'] StatusString::descriptionsByValue([StatusString::DISCARDED, StatusString::ACCEPTED]); // ['D' => 'No longer useful', 'A' => 'Recognized valid'] StatusString::colorsByValue([Status::PENDING, Status::DISCARDED]); // ['P' => '#000000', 'D' => '#FF0000'] // Forcing language StatusString::descriptionsByValue(null, 'it'); // 🇮🇹 ['P' => 'In attesa','A' => 'Accettato',... // Subset and language Status::descriptionsByValue([StatusString::DISCARDED, StatusString::NO_RESPONSE], 'it'); // 🇮🇹 ['DISCARDED' => 'Rifiutato','NO_RESPONSE' => 'Nessuna Risposta',...