Enum PHP : backed enums, from(), tryFrom() et cases()

Une enum PHP (PHP 8.1+) définit un type avec un ensemble fixe de valeurs possibles, ses cases : enum Status { case Active; case Banned; }. Vous utilisez un case sous la forme Status::Active, et un paramètre typé Status n'accepte rien d'autre. Une enum adossée (backed enum), enum Status: string, donne aussi à chaque case une valeur que vous pouvez stocker et reconvertir avec Status::from().

<?php
enum Status: string
{
    case Active = 'active';
    case Pending = 'pending';
    case Banned = 'banned';
}

function canLogIn(Status $status): bool
{
    return $status === Status::Active;
}

$s = Status::Pending;
echo $s->name, ' = ', $s->value, "\n";
var_dump(canLogIn($s), canLogIn(Status::Active));

// From a value stored in a database or a form
$fromDb = Status::from('banned');
echo $fromDb->name, "\n";

Avant les enums, on utilisait une liste de constantes de type chaîne, et rien n'empêchait une faute de frappe comme 'actve' d'atteindre la base de données. Avec Status comme type de paramètre, seuls les trois cases peuvent être passés.

Enums pures et enums adossées

Une enum pure a des cases qui ne sont que des noms. Une enum adossée déclare un type après le nom, int ou string, et chaque case doit alors avoir une valeur unique de ce type. Chaque case a ->name ; seuls les cases adossés ont ->value.

<?php
enum Suit
{
    case Hearts;
    case Spades;
}

enum Priority: int
{
    case Low = 1;
    case Normal = 5;
    case Urgent = 10;
}

$card = Suit::Hearts;
echo $card->name, "\n";
var_dump($card === Suit::Hearts, $card instanceof Suit);

$p = Priority::Urgent;
echo $p->name, ' = ', $p->value, "\n";
var_dump(Priority::Low->value < Priority::Urgent->value);
var_dump($p);

Prenez une enum adossée chaque fois que la valeur sort du programme : une colonne de base de données, une URL, un champ de formulaire, du JSON. Prenez une enum pure pour les valeurs qui n'existent que dans le code, comme l'état d'un analyseur.

Convertir une valeur avec from() et tryFrom()

Les enums adossées reçoivent deux méthodes statiques pour retransformer une valeur stockée en case. from() lève une ValueError pour une valeur inconnue ; tryFrom() renvoie null, ce qui se combine bien avec ?? pour une valeur par défaut :

<?php
enum Size: string
{
    case Small = 's';
    case Medium = 'm';
    case Large = 'l';
}

var_dump(Size::from('m'));
var_dump(Size::tryFrom('xl'));

$size = Size::tryFrom('xl') ?? Size::Medium;
echo "Using {$size->name}\n";

try {
    Size::from('xl');
} catch (ValueError $e) {
    echo get_class($e), ': ', $e->getMessage(), "\n";
}

Utilisez tryFrom() sur tout ce qu'un utilisateur vous a envoyé, et from() sur les valeurs que votre propre code a écrites, où une valeur inconnue signale un bug dont vous voulez être averti. L'argument suit les règles normales de type des paramètres : sur une enum int, Priority::from('5') renvoie Priority::Normal en mode par défaut car '5' est d'abord converti en 5, Priority::from('5x') est une TypeError, et avec declare(strict_types=1) toute chaîne est une TypeError. Cela vaut aussi pour tryFrom() : Priority::tryFrom('abc') lève une erreur au lieu de renvoyer null, vérifiez donc d'abord une saisie de formulaire destinée à une enum int avec filter_var($raw, FILTER_VALIDATE_INT).

Lister tous les cases avec cases()

Enum::cases() renvoie un tableau de tous les cases, dans l'ordre de déclaration. C'est ainsi qu'on construit une liste déroulante, qu'on valide une liste ou qu'on obtient toutes les valeurs avec array_column :

<?php
enum Plan: string
{
    case Free = 'free';
    case Pro = 'pro';
    case Team = 'team';

    public function label(): string
    {
        return match ($this) {
            Plan::Free => 'Free',
            Plan::Pro => 'Pro, 9 EUR a month',
            Plan::Team => 'Team, 29 EUR a month',
        };
    }
}

$chosen = Plan::tryFrom($_POST['plan'] ?? '');

echo '<form method="post"><select name="plan">';
foreach (Plan::cases() as $plan) {
    $selected = $plan === $chosen ? ' selected' : '';
    echo "<option value=\"{$plan->value}\"$selected>{$plan->label()}</option>";
}
echo '</select> <button>Choose</button></form>';

if ($chosen !== null) {
    echo "<p>You picked <b>{$chosen->name}</b> (stored as '{$chosen->value}').</p>";
}

echo '<pre>', implode(', ', array_column(Plan::cases(), 'value')), '</pre>';

Exécutez-le, choisissez une offre et cliquez sur Choose : le même script s'exécute à nouveau avec $_POST['plan'] rempli, et tryFrom() retransforme la chaîne envoyée en case Plan. Une valeur falsifiée comme plan=gold donne null, et aucune option n'est sélectionnée.

Méthodes, constantes et interfaces d'enum

Les enums peuvent avoir des méthodes, des méthodes statiques et des constantes, et implémenter des interfaces. Dans une méthode, $this est le case courant, ce qui fait de match ($this) la façon naturelle d'associer des données à chaque case. Ce qu'une enum ne peut pas avoir, ce sont des propriétés : les données propres à chaque case viennent de méthodes.

<?php
interface HasColor
{
    public function color(): string;
}

enum OrderState: string implements HasColor
{
    case New = 'new';
    case Shipped = 'shipped';
    case Delivered = 'delivered';
    case Cancelled = 'cancelled';

    const DEFAULT = self::New;

    public function color(): string
    {
        return match ($this) {
            self::New => 'blue',
            self::Shipped => 'orange',
            self::Delivered => 'green',
            self::Cancelled => 'grey',
        };
    }

    public function isFinal(): bool
    {
        return in_array($this, [self::Delivered, self::Cancelled], true);
    }

    public static function open(): array
    {
        return array_filter(self::cases(), fn (self $s) => !$s->isFinal());
    }
}

$state = OrderState::DEFAULT;
echo "{$state->name} is {$state->color()}\n";
var_dump(OrderState::Delivered->isFinal());
echo implode(', ', array_map(fn ($s) => $s->name, OrderState::open())), "\n";
var_dump($state instanceof HasColor);

Les enums dans match

match compare avec ===, et un case n'est identique qu'à lui-même, donc match et les enums vont bien ensemble. Si vous oubliez un case et que ce case atteint le match, PHP lève une UnhandledMatchError au lieu de ne rien renvoyer en silence :

<?php
enum Weekday: int
{
    case Mon = 1;
    case Tue = 2;
    case Wed = 3;
    case Thu = 4;
    case Fri = 5;
    case Sat = 6;
    case Sun = 7;
}

function kind(Weekday $d): string
{
    return match ($d) {
        Weekday::Sat, Weekday::Sun => 'weekend',
        default => 'workday',
    };
}

foreach ([Weekday::Fri, Weekday::Sat, Weekday::from(1)] as $day) {
    echo $day->name, ': ', kind($day), "\n";
}

$tomorrow = Weekday::tryFrom(Weekday::Sun->value + 1) ?? Weekday::Mon;
echo 'After Sun comes ', $tomorrow->name, "\n";

Voir match pour la différence entre match et switch.

Les enums en JSON et en chaîne

json_encode() écrit un case adossé sous forme de sa valeur. Une enum pure ne peut pas être encodée, et un echo de n'importe quel case échoue, car une enum est un objet, pas une chaîne. Affichez plutôt ->value ou ->name :

<?php
enum Role: string
{
    case Admin = 'admin';
    case Editor = 'editor';
}

$user = ['name' => 'Ada', 'role' => Role::Admin];
echo json_encode($user), "\n";

$data = json_decode('{"name":"Linus","role":"editor"}', true);
$role = Role::from($data['role']);
var_dump($role);

echo 'Role: ' . $role->value . "\n";
echo 'Name: ' . $role->name . "\n";

echo Role::Admin; lève une Error (« Object of class Role could not be converted to string »), et les enums ne peuvent pas implémenter __toString(). Au retour, le JSON donne une simple chaîne, convertissez-la donc avec from() ou tryFrom() comme montré. L'encodage est détaillé dans json_encode.

Erreurs fréquentes avec les enums

Trois erreurs reviennent sans cesse. Un case n'est jamais égal à sa valeur, un case ne peut pas être une clé de tableau, et new ne fonctionne pas sur une enum :

<?php
enum Status: string
{
    case Active = 'active';
    case Banned = 'banned';
}

// 1. A case is an object, not its value
var_dump(Status::Active == 'active');          // false
var_dump(Status::Active->value === 'active');  // true

// 2. Use ->value as an array key
$counts = [];
foreach ([Status::Active, Status::Banned, Status::Active] as $s) {
    $counts[$s->value] = ($counts[$s->value] ?? 0) + 1;
}
print_r($counts);

try {
    $bad = [Status::Active => 1];
} catch (TypeError $e) {
    echo 'Array key: ', $e->getMessage(), "\n";
}

// 3. Cases are created by PHP, never with new
try {
    $s = new Status();
} catch (Error $e) {
    echo $e->getMessage(), "\n";
}

S'il vous faut une table indexée par les cases eux-mêmes, utilisez SplObjectStorage ou WeakMap, qui acceptent des objets comme clés.