Download the PHP package elao/enum without Composer

Elao Enumerations

Provides additional, opinionated features to the PHP 8.1+ native enums as well as specific integrations with frameworks and libraries.

📢 This project used to emulate enumerations before PHP 8.1.
For the 1.x documentation, click here

You can also consult this issue to follow objectives & progress for the V2 of this lib.

• Features
  • Readable enums
  • Flag enums
  • Extra values
• Integrations
  • Symfony Forms
  • Symfony Controller Argument Resolver
  • Symfony VarDumper
  • Symfony Translation
  • Doctrine ORM
  • Doctrine ODM
  • Faker

Installation

Or, in order to help and test latest changes:

Readable enums

Readable enums provide a way to expose human-readable labels for your enum cases, by adding a new ReadableEnumInterface contract to your enums.

The easiest way to implement this interface is by using the ReadableEnumTrait and the EnumCase attribute:

The following snippet shows how to get the human-readable value of an enum:

It defines a proper contract to expose an enum case label instead of using the enum case internal name. Which is especially useful if the locale to expose labels to your users differs from the one you're writing your code, as well as for creating integrations with libraries requiring to expose such labels.

It's also especially useful in conjunction with a translation library like Symfony's Translation component, by using translation keys.

Given the following translation file:

Configure suffix/prefix & default value

As a shorcut, you can also use the ReadableEnum attribute to define the common suffix and prefix to use, as well as defaulting on the enum case name or value, if not provided explicitly:

using the case value (only for string backed enums):

Extra values

The EnumCase attributes also provides you a way to configure some extra attributes on your cases and access these easily with the ExtrasTrait:

Access these infos using ExtrasTrait::getExtra(string $key, bool $throwOnMissingExtra = false): mixed:

or create your own interfaces/traits:

Flag enums

Flagged enumerations are used for bitwise operations.

Each enumerated case is a bit flag and can be combined with other cases into a bitmask and manipulated using a FlagBag object:

Hence, using FlagBag::getValue() you can get an encoded value for any combination of flags from your enum, and use it for storage or communication between your processes.

Integrations

Symfony Form

Symfony already provides an EnumType for allowing the user to choose one or more options defined in a PHP enumeration.
It extends the ChoiceType field and defines the same options.

However, it uses the enum case name as label, which might not be convenient.
Since this library specifically supports readable enums, it ships its own EnumType, extending Symfony's one and using the human representation of each case instead of their names.

Use it instead of Symfony's one:

FlagBag Form Type

If you want to use FlagBag in Symfony Forms, use the FlagBagType. This type also extends Symfony EnumType, but it transforms form values to and from FlagBag instances.

Symfony HttpKernel

Resolve controller arguments from route path

As of Symfony 6.1+, backed enum cases will be resolved from route path parameters:

➜ A call to /cards/H will resolve the $suit argument as the Suit::Hearts enum case.

If you're not yet using Symfony HttpKernel 6.1+, this library will still make this working by registering its own resolver.

Resolve controller arguments from query or body

You can also resolve from query params or from the request body:

➜ A call to /cards?suit=H will resolve the $suit argument as the Suit::Hearts enum case.

Use BackedEnumFromBody to resolve from the request body ($_POST).

It also supports variadics:

➜ A call to /cards?suits[]=H&suits[]=S will resolve the $suits argument as [Suit::Hearts, Suit::Spades].

Symfony Translation

Because the ReadableEnumInterface can be translated within the TranslatorInterface, it is easy to use TranslatableInterface to enums.

To translate readable enums is just matter to have a call:

An interface and a trait have been added for that purpose.

We then use in PHP:

Or in Twig:

Doctrine

As of doctrine/orm 2.11, PHP 8.1 enum types are supported natively:

Note: Unless you have specific needs for a DBAL type as described below, we recommend using the official ORM integration for backed enums.

PhpEnums however also provides some base classes to save your PHP backed enumerations in your database. Custom DBAL classes for use-cases specific to this library, such as storing a flag bag or a collection of backed enum cases, are or will also be available.

In a Symfony app

This configuration is equivalent to the following sections explaining how to create a custom Doctrine DBAL type:

It'll actually generate & register the types classes for you, saving you from writing this boilerplate code.

Manually

Read the Doctrine DBAL docs first.

Extend the AbstractEnumType:

In your application bootstrapping code:

To convert the underlying database type of your new "Suit" type directly into an instance of Suit when performing schema operations, the type has to be registered with the database platform as well:

Then, use it as a column type:

Troubleshooting

Using enum instances with a QueryBuilder

When using enum instance as parameters in a query made with Doctrine\ORM\QueryBuilder and generated DBAL types from the bundle, parameter type might not be inferred correctly.

Either explicitly use enum value instead of an instance, or pass the registered DBAL type as the 3rd parameter in setParameter() to allow the query builder to cast the object to the database value correctly.

I.E, given:

Use one of the following methods:

Doctrine ODM

You can store enumeration values as string or integer in your MongoDB database and manipulate them as objects thanks to custom mapping types included in this library.

In a near future, custom ODM classes for use-cases specific to this library, such as storing a flag bag or a collection of backed enum cases, would also be provided.

In a Symfony app

This configuration is equivalent to the following sections explaining how to create a custom Doctrine ODM type:

It'll actually generate & register the types classes for you, saving you from writing this boilerplate code.

Manually

Read the Doctrine ODM docs first.

Extend the AbstractCollectionEnumType:

In your application bootstrapping code:

Mapping

Now the new type can be used when mapping fields:

Faker

The PhpEnums library provides a faker EnumProvider allowing to select random enum cases:

Its constructor receives a mapping of enum types aliases as first argument:

This is especially useful when using this provider with Nelmio Alice's DSL (see next section)

Usage with Alice

If you're using the nelmio/alice package and its bundle in order to generate fixtures, you can register the Faker provider by using the nelmio_alice.faker.generator:

The following example shows how to use the provider within a PHP fixture file: