Download the PHP package suleymanozev/enum-helper without Composer

Enum Helper

A simple and opinionated collections of PHP 8.1 enum helpers inspired by archtechx/enums and BenSampo/laravel-enum.
This package is framework agnostic, but if you use Laravel consider to use this linked package suleymanozev/laravel-enum-helper.

Functionalities summary

• Invokable cases: get the value of enum "invoking" it statically
• Construct enum by name or value: from(), tryFrom(), fromName(), tryFromName(), fromValue(), tryFromValue() methods
• 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(),nullableDescriptionsByValue())

Installation

PHP 8.1+ is required.

Usage

You can use the traits you need, but for convenience, you can use only the EnumHelper trait that includes (EnumInvokable, EnumFroms, EnumNames, EnumValues, EnumInspection, EnumEquality).
EnumDescription and EnumUniqueId are separated from EnumHelper because they cover edge cases.

The helper support both pure enum (e.g. PureEnum, PascalCasePureEnum) and BackedEnum (e.g. IntBackedEnum, StringBackedEnum).

In all examples we'll use the classes described below:

The package works with cases written in UPPER_CASE, snake_case and PascalCase.

Jump To

• Invokable Cases
• Froms
• Enums Inspection
• Enums Equality
• Names
• Values
• Unique ID
• Descriptions & Translations

Invokable Cases

This helper lets you get the value of a BackedEnum, or the name of a pure enum, by "invoking" it both statically (PureEnum::pending()), and as an instance ($status()).
A good approach is to call methods in camelCase mode, but you can invoke the enum in all cases ::STATICALLY(), ::statically() or ::Statically().

That way permits you to use enum invoke into an array keys definition:

or in database interactions $db_field_definition->default(PureEnum::pending()) or invoke instances to get the primitive value

Examples use static calls to get the primitive value

IDE code completion

To have a code completion you can get autosuggestions while typing the enum case and then add () or you can add phpDoc @method tags to the enum class to define all invokable cases like this:

From FromName

This helper adds from() and tryFrom() to pure enums, fromValue() and tryFromValue() (alias of from() and tryFrom()), fromName() and tryFromName() to all enums

Important Notes:

• BackedEnum instances already implement their own from() and tryFrom() methods, which will not be overridden by this trait.

from()

tryFrom()

fromName()

tryFromName()

Inspection

This helper permits check the type of enum (isPure(),isBacked()) and if enum contains a case name or value (has(), doesntHave(), hasName(), doesntHaveName(), hasValue(), doesntHaveValue()).

isPure() and isBacked()

With these methods you can check the type of the enum instance.

has() and doesntHave()

has() method permit checking if an enum has a case (name or value) by passing int, string or enum instance. For convenience, there is also an doesntHave() method which is the exact reverse of the has() method.

`

hasName() and doesntHaveName()

hasName() method permit checking if an enum has a case name. For convenience, there is also an doesntHaveName() method which is the exact reverse of the hasName() method.

`

hasValue() and doesntHaveValue()

hasValue() method permit checking if an enum has a case by passing int, string or enum instance. For convenience, there is also an doesntHaveValue() method which is the exact reverse of the hasValue() method.

`

Equality

This helper permits to compare an enum instance (is(),isNot()) and search if it is present inside an array (in(),notIn()).

is() and isNot()

is() method permit checking the equality of an instance against an enum instance, a case name, or a case value.
For convenience, there is also an isNot() method which is the exact reverse of the is() method.

in() and notIn()

in() method permit to see if an instance matches on an array of instances, names or values. For convenience, there is also a notIn() method which is the exact reverse of the i() method.

Names

This helper offer names() and namesByValue() methods.

names()

This method returns a list of case names in the enum.

namesByValue()

This method returns an associative array of [value => name] on BackedEnum, [name => name] on pure enum.

Values

This helper offer values() and valuesByName() methods.

values()

This method returns a list of case values for BackedEnum or a list of case names for pure enums.

valuesByName()

This method returns a associative array of [name => value] on BackedEnum, [name => name] on pure enum.

UniqueId

This helper permits to get an unique identifier from enum or an enum instance from identifier.

The helper is not included on the base EnumHelper trait and does not depend on it, so if you need it you must use EnumUniqueId.

uniqueId()

This method returns the enum unique identifier based on Namespace\ClassName.CASE_NAME. You can use this identifier to save multiple types of enums in a database on a polymorphic column.

fromUniqueId()

This method returns an enum instance from unique identifier.

Global getEnumFromUniqueId() helper

The method fromUniqueId() has little possibility of use because it's related to only an enum class. A better approach is to create a global helper to instantiate any enum from uniqueId like this:

Descriptions and Translations

This helper permits to have a description of each case of an enum. Work with both singular language and multilingual application. This is useful when you need descriptions to characterize the cases better or in a multilingual context.

The helper is not included on the base EnumHelper trait and does not depend on it, so if you need it you must use EnumDescription and implement the abstract description() method to define the descriptions. You can use it on both pure enums and BackedEnum.

After the implementation of description() method you can use it

Localization

You can change the description() method with your translation method/helper to translate the descriptions.

After the implementation of description method you can use it

descriptions()

This method returns a list of case descriptions of enum.

descriptionsByValue()

This method returns an associative array of [value => description] on BackedEnum, [name => description] on pure enum.

nullableDescriptionsByValue()

This method prepend to descriptionsByValue() returns a default value usefull when do you need nullable select on a form.

Special Thanks

• Datomatic Team