Commandes

Quatre commandes sont enregistrées lorsque symfony/console est installé (phil:enums:check-sets exige aussi doctrine/orm), ainsi que make:enum avec MakerBundle. Les deux premières lisent les enums déclarées sous les paths configurés (Configuration). Le chercheur lit les jetons de chaque fichier PHP (l'espace de noms, puis chaque déclaration enum) et conserve les enums que l'autoloader trouve : un fichier hors de la carte de l'autoloader n'apporte donc rien.

debug:enums

Sans argument, la commande affiche les enums des chemins, avec leur type sous-jacent, leur nombre de cas et le fait qu'elles soient traduisibles ou non :

$ bin/console debug:enums
 ------------------------- --------- ------- --------------
  Enum                      Backing   Cases   Translatable
 ------------------------- --------- ------- --------------
  App\Order\OrderStatus     string    4       yes
  App\Security\Permission   int       3       no
 ------------------------- --------- ------- --------------

Avec une enum (sa classe, ou son nom court s'il ne désigne qu'une seule enum), elle affiche ses cas : valeur, libellé, description, groupes, poids, et les marques default et deprecated.

$ bin/console debug:enums Permission
 ------- ------- ------- --------------- --------------- -------- ------------
  Case    Value   Label   Description     Groups          Weight   Marks
 ------- ------- ------- --------------- --------------- -------- ------------
  Read    1       Read                    basic           1        default
  Write   2       Write                   basic, editor   1
  Admin   4       Admin   Every right.                    0        deprecated
 ------- ------- ------- --------------- --------------- -------- ------------

Elle avertit pour chaque cas auquel il manque une méta-propriété exigée par le #[RequiredMeta] de l'enum. Avec --locale=fr, elle liste les clés de libellé et de description d'une enum traduisible qui n'ont pas de traduction dans cette locale et ce domaine : ce sont les clés que translation:extract ajouterait.

Elle échoue, avec le code de sortie 1, lorsque le nom ne correspond à aucune enum ou à plusieurs, lorsqu'il manque à un cas une métadonnée exigée, ou lorsqu'une clé n'a pas de traduction. Lancez-la en intégration continue pour que vos enums restent libellées et traduites.

phil:enums:typescript

Écrit des enums en TypeScript, pour que le côté client partage leurs valeurs et leurs libellés au lieu de les copier :

$ bin/console phil:enums:typescript --output=assets/enums.ts
$ bin/console phil:enums:typescript 'App\Order\OrderStatus' --locale=fr

// Generated by phil/enums-bundle; do not edit.

export const OrderStatus = {
  PENDING: "pending",
  /** @deprecated */
  ON_HOLD: "on_hold",
} as const;
export type OrderStatus = (typeof OrderStatus)[keyof typeof OrderStatus];
export const OrderStatusLabels: Record<OrderStatus, string> = {
  "pending": "En attente",
  "on_hold": "Suspendue",
};

• Un objet de constantes, un type union et un enregistrement de libellés par enum, nommés d'après son nom court. Deux enums de même nom court sont refusées : exportez-les séparément.
• Une enum pure s'écrit par ses noms.
• Les cas obsolètes sont conservés, marqués @deprecated : le côté client lit encore des enregistrements qui en contiennent.
• Ce que l'enum déclare à côté suit lorsqu'elle en a : <Enum>Descriptions pour les cas qui ont une Description, <Enum>Groups pour ses #[Group], <Enum>Default pour son #[DefaultCase].

Faites un commit du fichier généré, ou générez-le dans la construction du côté client ; relancez la commande lorsqu'une enum change.

phil:enums:icu

Écrit un message ICU select sur les cas d'une enum, pour traduire une phrase qui change selon le cas, plutôt que le cas seul :

$ bin/console phil:enums:icu 'App\Order\OrderStatus' --argument=status --locale=fr
{status, select, pending {En attente} paid {Payée} shipped {Expédiée} other {}}

Chaque branche a pour clé la valeur du cas (son nom en snake case pour une enum pure) et pour texte le libellé du cas, traduit selon --locale. Collez le message dans un catalogue au format +intl-icu, puis écrivez la phrase de chaque branche. Les accolades et les apostrophes d'un libellé sont protégées comme l'exige ICU.

Une clé doit être un mot-clé ICU, qui ne contient ni espace ni ponctuation : une valeur comme in-progress, v1.2 ou a b donnerait un message que MessageFormatter refuse. La commande vérifie que chaque clé ne contient que des lettres, des marques, des chiffres et des traits de soulignement, qu'elle n'est pas other (la branche qu'ICU exige) et qu'elle n'apparaît qu'une fois (deux cas purs FooBar et Foo_Bar partagent foo_bar). Sinon, elle échoue avec un message qui nomme le cas et n'écrit rien. Le nom donné à --argument est vérifié de la même façon. Donnez à un tel cas une valeur qu'ICU accepte (in_progress).

phil:enums:check-sets

Lit chaque valeur stockée de chaque colonne EnumSet que les entités font correspondre, et liste celles qui ne désignent plus de cas : un cas retiré, un indicateur renuméroté (Doctrine). Elle échoue dès qu'elle en liste une.

make:enum

Lorsque MakerBundle est installé, make:enum écrit une nouvelle enum dans l'espace de noms Enum\ de l'application, avec AsEnumerableEnumTrait, #[Meta(Label::class)] et un Label sur chaque cas :

$ bin/console make:enum OrderStatus --case=Pending --case=InTransit --translatable

#[Meta(Label::class)]
enum OrderStatus: string implements TranslatableInterface
{
    use AsEnumerableEnumTrait;
    use AsTranslatableEnumTrait;

    #[Label('Pending')]
    case Pending = 'pending';

    #[Label('In transit')]
    case InTransit = 'in_transit';
}

Un nom qui n'est pas un identifiant PHP, ou qui apparaît deux fois, est refusé. Pour une enum de chaînes, deux noms dont les mots donnent la même valeur (FooBar et Foo_Bar, ACTIVE et Active) le sont aussi, car PHP les refuserait dans l'enum écrite. Les libellés sont les noms écrits en mots : InTransit et IN_TRANSIT donnent tous deux In transit.