PHP Enum: Backed Enums, from(), tryFrom() und cases()

Q: Wie bekomme ich in PHP den Wert eines Enums?

Bei einem Backed Enum liest du ->value: Status::Active->value ist 'active'. Jeder Case hat außerdem ->name, den Namen des Case als String ('Active'). Ein Pure Enum (ohne : string oder : int) hat nur ->name.

Q: Was ist der Unterschied zwischen from() und tryFrom() bei PHP-Enums?

Beide machen aus einem Wert einen Case eines Backed Enums. Status::from('active') liefert den Case oder wirft einen ValueError, wenn kein Case diesen Wert hat; Status::tryFrom('nope') liefert stattdessen null. Verwende tryFrom() für Nutzereingaben und from(), wenn ein falscher Wert ein Bug ist.

Q: Wie bekomme ich in PHP alle Werte eines Enums?

Status::cases() liefert jeden Case in der Reihenfolge der Deklaration. Für die Werte eines Backed Enums verwendest du arraycolumn(Status::cases(), 'value'), für die Namen arraycolumn(Status::cases(), 'name').

Q: Was ist der Unterschied zwischen einem Pure Enum und einem Backed Enum?

Ein Pure Enum (enum Suit { case Hearts; }) hat Cases, die nur Namen sind. Ein Backed Enum (enum Suit: string { case Hearts = 'H'; }) gibt jedem Case einen eindeutigen Wert vom Typ int oder string, den du brauchst, um ihn in einer Datenbank zu speichern, in ein Formular oder JSON zu schreiben und mit from() oder tryFrom() zurückzuwandeln.

Ein PHP-Enum (PHP 8.1+) definiert einen Typ mit einer festen Menge möglicher Werte, seinen Cases: enum Status { case Active; case Banned; }. Du verwendest einen Case als Status::Active, und ein Parameter vom Typ Status akzeptiert nichts anderes. Ein Backed Enum, enum Status: string, gibt jedem Case außerdem einen Wert, den du speichern und mit Status::from() zurückwandeln kannst.

<?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";

Vor Enums war dasselbe eine Liste von String-Konstanten, und nichts hielt einen Tippfehler wie 'actve' davon ab, in der Datenbank zu landen. Mit Status als Parametertyp lassen sich nur die drei Cases übergeben.

Pure Enums und Backed Enums

Ein Pure Enum hat Cases, die nur Namen sind. Ein Backed Enum deklariert nach dem Namen einen Typ, int oder string, und jeder Case muss dann einen eindeutigen Wert dieses Typs haben. Jeder Case hat ->name; nur Backed Cases haben ->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);

Wähl ein Backed Enum, sobald der Wert das Programm verlässt: eine Datenbankspalte, eine URL, ein Formularfeld, JSON. Wähl ein Pure Enum für Werte, die nur im Code existieren, etwa den Zustand eines Parsers.

Einen Wert mit from() und tryFrom() umwandeln

Backed Enums bekommen zwei statische Methoden, um einen gespeicherten Wert wieder in einen Case zu verwandeln. from() wirft bei einem unbekannten Wert einen ValueError; tryFrom() liefert null, was gut zu ?? für einen Standardwert passt:

<?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";
}

Verwende tryFrom() für alles, was ein Nutzer geschickt hat, und from() für Werte, die dein eigener Code geschrieben hat, wo ein unbekannter Wert einen Bug bedeutet, von dem du erfahren willst. Das Argument folgt den normalen Regeln für Parametertypen: Bei einem int-Enum liefert Priority::from('5') im Standardmodus Priority::Normal, weil '5' zuerst in 5 umgewandelt wird, Priority::from('5x') ist ein TypeError, und unter declare(strict_types=1) ist jeder String ein TypeError. Das gilt auch für tryFrom(): Priority::tryFrom('abc') wirft, statt null zu liefern, also prüfst du Formulareingaben für ein int-Enum vorher mit filter_var($raw, FILTER_VALIDATE_INT).

Alle Cases mit cases() auflisten

Enum::cases() liefert ein Array mit jedem Case, in der Reihenfolge der Deklaration. So baust du ein Dropdown, validierst eine Liste oder holst alle Werte mit 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>';

Führe es aus, wähle einen Tarif und klicke auf Choose: Dasselbe Skript läuft erneut, mit gefülltem $_POST['plan'], und tryFrom() macht aus dem gesendeten String wieder einen Plan-Case. Ein gefälschter Wert wie plan=gold ergibt null, und keine Option ist ausgewählt.

Enum-Methoden, Konstanten und Interfaces

Enums können Methoden, statische Methoden und Konstanten haben und Interfaces implementieren. In einer Methode ist $this der aktuelle Case, und deshalb ist match ($this) der natürliche Weg, jedem Case Daten zuzuordnen. Was ein Enum nicht haben kann, sind Eigenschaften: Daten pro Case kommen aus Methoden.

<?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);

Enums in match

match vergleicht mit ===, und ein Enum-Case ist nur mit sich selbst identisch, also passen match und Enums zusammen. Wenn du einen Case vergisst und genau dieser Case das match erreicht, wirft PHP einen UnhandledMatchError, statt still nichts zu liefern:

<?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";

Wie sich match von switch unterscheidet, steht unter match.

Enums in JSON und als Strings

json_encode() schreibt einen Backed Case als seinen Wert. Ein Pure Enum lässt sich nicht kodieren, und echo eines beliebigen Case scheitert, weil ein Enum ein Objekt ist und kein String. Gib stattdessen ->value oder ->name aus:

<?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; wirft einen Error („Object of class Role could not be converted to string“), und Enums können __toString() nicht implementieren. Auf dem Rückweg liefert JSON einen einfachen String, also wandelst du ihn wie gezeigt mit from() oder tryFrom() um. Mehr zum Kodieren unter json_encode.

Typische Fehler mit Enums

Drei Fehler tauchen immer wieder auf. Ein Case ist nie gleich seinem Wert, ein Case kann kein Array-Schlüssel sein, und new funktioniert bei einem Enum nicht:

<?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";
}

Wenn du eine Map mit den Cases selbst als Schlüssel brauchst, verwendest du SplObjectStorage oder WeakMap, die Objekte als Schlüssel akzeptieren.

Häufig gestellte Fragen

Wie bekomme ich in PHP den Wert eines Enums?

Bei einem Backed Enum liest du ->value: Status::Active->value ist 'active'. Jeder Case hat außerdem ->name, den Namen des Case als String ('Active'). Ein Pure Enum (ohne : string oder : int) hat nur ->name.

Was ist der Unterschied zwischen from() und tryFrom() bei PHP-Enums?

Beide machen aus einem Wert einen Case eines Backed Enums. Status::from('active') liefert den Case oder wirft einen ValueError, wenn kein Case diesen Wert hat; Status::tryFrom('nope') liefert stattdessen null. Verwende tryFrom() für Nutzereingaben und from(), wenn ein falscher Wert ein Bug ist.

Wie bekomme ich in PHP alle Werte eines Enums?

Status::cases() liefert jeden Case in der Reihenfolge der Deklaration. Für die Werte eines Backed Enums verwendest du array_column(Status::cases(), 'value'), für die Namen array_column(Status::cases(), 'name').

Was ist der Unterschied zwischen einem Pure Enum und einem Backed Enum?

Ein Pure Enum (enum Suit { case Hearts; }) hat Cases, die nur Namen sind. Ein Backed Enum (enum Suit: string { case Hearts = 'H'; }) gibt jedem Case einen eindeutigen Wert vom Typ int oder string, den du brauchst, um ihn in einer Datenbank zu speichern, in ein Formular oder JSON zu schreiben und mit from() oder tryFrom() zurückzuwandeln.

Kann ein PHP-Enum Methoden haben?

Ja. Enums können Methoden, statische Methoden und Konstanten haben und Interfaces implementieren. In einer Methode ist $this der aktuelle Case, also ist return match ($this) { self::Active => 'green', self::Banned => 'red' }; ein gängiges Muster. Eigenschaften können Enums nicht haben.

Verwandte Konzepte