php enum
1.8.4
La maintenance de ce projet est prise en charge via Tidelift.
Premièrement et surtout, SplEnum n'est pas intégré à PHP, vous devez installer l'extension séparément.
L'utilisation d'une énumération au lieu de constantes de classe offre les avantages suivants :
Vous pouvez utiliser une énumération comme type de paramètre : function setAction(Action $action) {
Vous pouvez utiliser une énumération comme type de retour : function getAction() : Action {
Vous pouvez enrichir l'énumération avec des méthodes (par exemple format , parse , …)
Vous pouvez étendre l'énumération pour ajouter de nouvelles valeurs (rendre votre énumération final pour l'empêcher)
Vous pouvez obtenir une liste de toutes les valeurs possibles (voir ci-dessous)
Cette classe Enum n'est pas destinée à remplacer les constantes de classe, mais uniquement à être utilisée lorsque cela a du sens.
composer require myclabs/php-enum
use MyCLabsEnumEnum;/** * Action enum * * @extends Enum<Action::*> */final class Action extends Enum
{private const VIEW = 'view';private const EDIT = 'edit';
}$action = Action::VIEW();// ou avec une clé dynamique :$action = Action::$key();// ou avec une valeur dynamique :$action = Action::from($value);/ / ou$action = nouvelle Action($valeur);
Comme vous pouvez le constater, les méthodes statiques sont automatiquement implémentées pour fournir un accès rapide à une valeur d'énumération.
Un avantage par rapport à l'utilisation de constantes de classe est de pouvoir utiliser une énumération comme type de paramètre :
fonction setAction(Action $action) {// ...} __construct() Le constructeur vérifie que la valeur existe dans l'énumération
__toString() Vous pouvez echo $myValue , il affichera la valeur enum (valeur de la constante)
getValue() Renvoie la valeur actuelle de l'énumération
getKey() Renvoie la clé de la valeur actuelle sur Enum
equals() Teste si les instances d'énumération sont égales (renvoie true si les valeurs d'énumération sont égales, false sinon)
Méthodes statiques :
from() Crée une instance Enum, vérifiant que la valeur existe dans l'énumération
Méthode toArray() Renvoie toutes les valeurs possibles sous forme de tableau (nom constant dans la clé, valeur constante dans la valeur)
keys() Renvoie les noms (clés) de toutes les constantes de la classe Enum
values() Renvoie les instances de la classe Enum de toutes les constantes Enum (nom de constante dans la clé, instance Enum dans la valeur)
isValid() Vérifiez si la valeur testée est valide sur l'ensemble d'énumérations
isValidKey() Vérifiez si la clé testée est valide sur l'ensemble d'énumérations
assertValidValue() Affirmer que la valeur est valide sur l'ensemble d'énumérations, en lançant une exception sinon
search() Clé de retour pour la valeur recherchée
L'action de classe finale étend Enum
{private const VIEW = 'view';private const EDIT = 'edit';
}// Méthode statique :$action = Action::VIEW();$action = Action::EDIT(); Les assistants de méthode statique sont implémentés à l'aide de __callStatic() .
Si vous vous souciez de la saisie semi-automatique de l'EDI, vous pouvez soit implémenter les méthodes statiques vous-même :
L'action de classe finale étend Enum
{private const VIEW = 'view';/** * @return Action */public static function VIEW() {return new Action(self::VIEW);
}
}ou vous pouvez utiliser phpdoc (ceci est supporté dans PhpStorm par exemple) :
/** * @method static Action VIEW() * @method static Action EDIT() */final class Action extends Enum
{private const VIEW = 'view';private const EDIT = 'edit';
} L'énumération native est arrivée sur PHP dans la version 8.1 : https://www.php.net/enumerations
Si votre projet exécute PHP 8.1+ ou si votre bibliothèque l'a comme exigence minimale, vous devez l'utiliser à la place de cette bibliothèque.
Lors de la migration depuis myclabs/php-enum , l'effort devrait être faible si l'utilisation se déroule de la manière recommandée :
constantes privées
cours finaux
aucune méthode remplacée
Modifications pour la migration :
La définition de classe doit être modifiée de
/** * @method static Action VIEW() * @method static Action EDIT() */final class Action extends Enum
{private const VIEW = 'view';private const EDIT = 'edit';
}à
enum Action : string{case VIEW = 'view';case EDIT = 'edit';
}Tous les endroits où la classe était utilisée comme type continueront à fonctionner.
Utilisations et changement nécessaire :
| Opération | myclabs/php-enum | énumération native |
|---|---|---|
| Obtenir une instance changera de | $enumCase = Action::VIEW() | $enumCase = Action::VIEW |
| Créer une énumération à partir d'une valeur sauvegardée | $enumCase = new Action('view') | $enumCase = Action::from('view') |
| Obtenez la valeur sauvegardée de l'instance enum | $enumCase->getValue() | $enumCase->value |
| Comparez deux instances d'énumération | $enumCase1 == $enumCase2ou $enumCase1->equals($enumCase2) | $enumCase1 === $enumCase2 |
| Obtenez la clé/le nom de l'instance d'énumération | $enumCase->getKey() | $enumCase->name |
| Obtenez une liste de toutes les instances possibles de l'énumération | Action::values() | Action::cases() |
| Obtenez une carte des instances possibles de l'énumération mappée par nom | Action::values() | array_combine(array_map(fn($case) => $case->name, Action::cases()), Action::cases())ou (new ReflectionEnum(Action::class))->getConstants() |
| Obtenez une liste de tous les noms possibles de l'énumération | Action::keys() | array_map(fn($case) => $case->name, Action::cases()) |
| Obtenez une liste de toutes les valeurs sauvegardées possibles de l'énumération | Action::toArray() | array_map(fn($case) => $case->value, Action::cases()) |
| Obtenez une carte des valeurs sauvegardées possibles de l'énumération mappée par nom | Action::toArray() | array_combine(array_map(fn($case) => $case->name, Action::cases()), array_map(fn($case) => $case->value, Action::cases()))ou array_map(fn($case) => $case->value, (new ReflectionEnum(Action::class))->getConstants())) |
Énumération native PHP 8.1+
Cartographie d'énumération de doctrine
Intégration Symfony ParamConverter
Intégration PHPStan
