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

A PHP enum (PHP 8.1+) defines a type with a fixed set of possible values, its cases: enum Status { case Active; case Banned; }. You use a case as Status::Active, and a parameter typed Status accepts nothing else. A backed enum, enum Status: string, also gives each case a value you can store and convert back with 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";

Before enums, the same thing was a list of string constants, and nothing stopped a typo like 'actve' from reaching the database. With Status as the parameter type, only the three cases can be passed in.

Pure enums and backed enums

A pure enum has cases that are only names. A backed enum declares a type after the name, int or string, and every case must then have a unique value of that type. Every case has ->name; only backed cases have ->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);

Pick a backed enum whenever the value leaves the program: a database column, a URL, a form field, JSON. Pick a pure enum for values that only exist inside the code, such as the state of a parser.

Convert a value with from() and tryFrom()

Backed enums get two static methods for turning a stored value back into a case. from() throws a ValueError for an unknown value; tryFrom() returns null, which pairs well with ?? for a default:

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

Use tryFrom() on anything a user sent you, and from() on values your own code wrote, where an unknown value means a bug you want to hear about. The argument follows the normal parameter type rules: on an int enum, Priority::from('5') returns Priority::Normal in the default mode because '5' is converted to 5 first, Priority::from('5x') is a TypeError, and under declare(strict_types=1) any string is a TypeError. That includes tryFrom(): Priority::tryFrom('abc') throws instead of returning null, so check form input for an int enum with filter_var($raw, FILTER_VALIDATE_INT) first.

List all cases with cases()

Enum::cases() returns an array of every case, in the order they are declared. That is how you build a dropdown, validate a list, or get all values with 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>';

Run it, pick a plan and press Choose: the same script runs again with $_POST['plan'] filled in, and tryFrom() turns the submitted string back into a Plan case. A forged value such as plan=gold gives null, and no option is selected.

Enum methods, constants and interfaces

Enums can have methods, static methods and constants, and can implement interfaces. Inside a method, $this is the current case, which makes match ($this) the natural way to attach data to each case. What an enum cannot have is properties: per-case data comes from methods.

<?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 compares with ===, and an enum case is identical only to itself, so match and enums fit together. If you forget a case and that case reaches the match, PHP throws an UnhandledMatchError instead of silently returning nothing:

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

See match for how match differs from switch.

Enums in JSON and as strings

json_encode() writes a backed case as its value. A pure enum cannot be encoded, and echo of any case fails, because an enum is an object, not a string. Print ->value or ->name instead:

<?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; throws an Error ("Object of class Role could not be converted to string"), and enums cannot implement __toString(). On the way back in, JSON gives a plain string, so convert it with from() or tryFrom() as shown. More on encoding in json_encode.

Common enum mistakes

Three errors come up again and again. A case is never equal to its value, a case cannot be an array key, and new does not work on an 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";
}

If you need a map keyed by the cases themselves, use SplObjectStorage or WeakMap, which accept objects as keys.