:nut_and_bolt: PHP 8.1+ 的扩展枚举功能以及与框架和库的特定集成
Provides additional, opinionated features to the PHP 8.1+ native enums as well as specific integrations with frameworks and libraries.
#[ReadableEnum(prefix: 'suit.')]
enum Suit: string implements ReadableEnumInterface
{
use ReadableEnumTrait;
case Hearts = '♥︎';
case Diamonds = '♦︎';
case Clubs = '♣︎';
case Spades = '︎♠︎';
}[!Important] Version 3.x introduces support for Symfony 8 and requires PHP 8.4+ and Symfony 6.4+ minimum.
For older PHP or Symfony versions, refer to the 2.x documentation (no longer maintained).
composer require "elao/enum:^2.0"Or, in order to help and test latest changes:
composer require "elao/enum:^2.x-dev"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:
namespace App\Enum;
use Elao\Enum\ReadableEnumInterface;
use Elao\Enum\ReadableEnumTrait;
use Elao\Enum\Attribute\EnumCase;
enum Suit: string implements ReadableEnumInterface
{
use ReadableEnumTrait;
#[EnumCase('suit.hearts')]
case Hearts = '♥︎';
#[EnumCase('suit.diamonds')]
case Diamonds = '♦︎';
#[EnumCase('suit.clubs')]
case Clubs = '♣︎';
#[EnumCase('suit.spades')]
case Spades = '︎♠︎';
}The following snippet shows how to get the human-readable value of an enum:
Suit::Hearts->getReadable(); // returns 'suit.hearts'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:
# translations/messages.fr.yaml
suit.hearts: 'Coeurs'
suit.diamonds: 'Carreaux'
suit.clubs: 'Piques'
suit.spades: 'Trèfles'$enum = Suit::Hearts;
$translator->trans($enum->getReadable(), locale: 'fr'); // returns 'Coeurs'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:
#[ReadableEnum(prefix: 'suit.')]
enum Suit: string implements ReadableEnumInterface
{
use ReadableEnumTrait;
#[EnumCase('hearts︎')]
case Hearts = '♥︎';
case Diamonds = '♦︎';
case Clubs = '♣︎';
case Spades = '︎♠︎';
}
Suit::Hearts->getReadable(); // returns 'suit.hearts'
Suit::Clubs->getReadable(); // returns 'suit.Clubs'using the case value (only for string backed enums):
#[ReadableEnum(prefix: 'suit.', useValueAsDefault: true)]
enum Suit: string implements ReadableEnumInterface
{
use ReadableEnumTrait;
case Hearts = 'hearts';
case Diamonds = 'diamonds';
case Clubs = 'clubs︎';
case Spades = '︎spades';
}
Suit::Hearts->getReadable(); // returns 'suit.hearts'
Suit::Clubs->getReadable(); // returns 'suit.clubs'The EnumCase attributes also provides you a way to configure some extra attributes on your cases and access these easily with the ExtrasTrait:
namespace App\Enum;
use Elao\Enum\ReadableEnumInterface;
use Elao\Enum\ExtrasTrait;
use Elao\Enum\Attribute\EnumCase;
enum Suit implements ReadableEnumInterface
{
use ExtrasTrait;
#[EnumCase(extras: ['icon' => 'fa-heart', 'color' => 'red'])]
case Hearts;
#[EnumCase(extras: ['icon' => 'fa-diamond', 'color' => 'red'])]
case Diamonds;
#[EnumCase(extras: ['icon' => 'fa-club', 'color' => 'black'])]
case Clubs;
#[EnumCase(extras: ['icon' => 'fa-spade', 'color' => 'black'])]
case Spades;
}Access these infos using ExtrasTrait::getExtra(string $key, bool $throwOnMissingExtra = false): mixed:
Suit::Hearts->getExtra('color'); // 'red'
Suit::Spades->getExtra('icon'); // 'fa-spade'
Suit::Spades->getExtra('missing-key'); // null
Suit::Spades->getExtra('missing-key', true); // throwsor create your own interfaces/traits:
…Flagged enumerations are used for bitwise operations.
…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.
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:
namespace App\Form\Type;
use App\Enum\Suit;
use Symfony\Component\Form\AbstractType;
use Elao\Enum\Bridge\Symfony\Form\Type\EnumType;
use Symfony\Component\Form\Extension\Core\Type\SubmitType;
use Symfony\Component\Form\FormBuilderInterface;
class CardType extends AbstractType
{
public function buildForm(FormBuilderInterface $builder, array $options): void
{
$builder
->add('suit', EnumType::class, [
'class' => Suit::class,
'expanded' => true,
])
;
}
// ...
}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.
namespace App\Form\Type;
use App\Enum\Permissions;
use Symfony\Component\Form\AbstractType;
use Elao\Enum\Bridge\Symfony\Form\Type\FlagBagType;
use Symfony\Component\Form\Extension\Core\Type\SubmitType;
use Symfony\Component\Form\FormBuilderInterface;
class AuthenticationType extends AbstractType
{
public function buildForm(FormBuilderInterface $builder, array $options): void
{
$builder
->add('permission', FlagBagType::class, [
'class' => Permissions::class,
])
;
}
// ...
}Symfony natively resolves backed enum cases from route path parameters:
class CardController
{
#[Route('/cards/{suit}')]
public function list(Suit $suit): Response { /* ... */ }
}Symfony natively resolves backed enum cases from query parameters using #[MapQueryParameter]:
use Symfony\Component\HttpKernel\Attribute\MapQueryParameter;
class DefaultController
{
#[Route('/cards')]
public function list(#[MapQueryParameter] ?Suit $suit = null): Response { /* ... */ }
}Symfony does not provide a native equivalent for resolving individual backed enum parameters from the request body.
This library provides the #[BackedEnumFromBody] attribute to fill this gap:
use Elao\Enum\Bridge\Symfony\HttpKernel\Controller\ArgumentResolver\Attributes\BackedEnumFromBody;
class DefaultController
{
#[Route('/cards', methods: 'POST')]
public function create(
#[BackedEnumFromBody]
Suit $suit,
): Response {
// [...]
}
}It also supports variadics:
class DefaultController
{
#[Route('/cards', methods: 'POST')]
public function create(
#[BackedEnumFromBody]
Suit ...$suits,
): Response {
// [...]
}
}➜ A POST to /cards with body suits[]=H&suits[]=S will resolve the $suits argument as [Suit::Hearts, Suit::Spades].
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:
public function trans(TranslatorInterface $translator, string $locale = null): string
{
return $translator->trans($this->getReadable(), [], $locale);
}An interface and a trait have been added for that purpose.
use Elao\Enum\Bridge\Symfony\Translation\TranslatableEnumInterface;
use Elao\Enum\Bridge\Symfony\Translation\TranslatableEnumTrait;
enum Card: string implements TranslatableEnumInterface
{
use TranslatableEnumTrait;
#[EnumCase('suit.hearts')]
case Hearts = '♥︎';
// ...
}We then use in PHP:
$translated = Card::Hearts->trans($this->translator)Or in Twig:
{{ game.card|trans }}As of doctrine/orm 2.11, PHP 8.1 enum types are supported natively:
#[Entity]
class Card
{
#[Column(type: 'string', enumType: Suit::class)]
public $suit;
}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.
This configuration is equivalent to the following sections explaining how to create a custom Doctrine DBAL type:
elao_enum:
doctrine:
types:
App\Enum\Suit: ~ # Defaults to `{ class: App\Enum\Suit, default: null, type: single }`
permissions: { class: App\Enum\Permission } # You can set a name different from the enum FQCN
permissions_bag: { class: App\Enum\Permissions, type: flagbag } # values are stored as an int and retrieved as FlagBag object
App\Enum\RequestStatus: { default: 200 } # Default value from enum cases, in case the db value is NULLIt'll actually generate & register the types classes for you, saving you from writing this boilerplate code.
Read the Doctrine DBAL docs first.
Extend the AbstractEnumType:
namespace App\Doctrine\DBAL\Type;
use Elao\Enum\Bridge\Doctrine\DBAL\Types\AbstractEnumType;
use App\Enum\Suit;
class SuitType extends AbstractEnumType
{
protected function getEnumClass(): string
{
return Suit::class; // By default, the enum FQCN is used as the DBAL type name as we暂无开放 Issues,或尚未同步最近议题。