suleymanozev / laravel-enum-helper
Simple opinionated framework agnostic PHP 8.1 enum helper for Laravel
Requires
- php: ^8.1
- composer/class-map-generator: ^1.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
- suleymanozev/enum-helper: ^1.0
Requires (Dev)
- laravel/pint: ^v1.13
- orchestra/testbench: ^6.23|^7.0
- pestphp/pest: ^1.21
- pestphp/pest-plugin-laravel: ^1.2
- phpstan/phpstan: ^1.7
README
This is an extension of the suleymanozev/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.
The enum-helper base package summary
You should see the suleymanozev/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 suleymanozev/laravel-enum-helper
Usage
You can use this functionality simply using the LaravelEnumHelper trait.
use Suleymanozev\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.
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',...
Special Thanks
- Datomatic Team