PHP 枚举 enum 教程：from()、tryFrom() 和 cases()

PHP 枚举（PHP 8.1+）定义了一个类型，它只有固定的几个可能取值，也就是它的 case：enum Status { case Active; case Banned; }。使用时写作 Status::Active，类型声明为 Status 的参数不接受其他任何值。backed 枚举（enum Status: string）还会给每个 case 一个值，你可以把它存起来，再用 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";

在有枚举之前，同样的功能靠一组字符串常量实现，没有什么能阻止 'actve' 这样的拼写错误写进数据库。把 Status 用作参数类型后，只能传入这三个 case。

纯枚举和 backed 枚举

纯枚举的 case 只有名称。backed 枚举在名称后面声明一个类型，int 或 string，然后每个 case 都必须有一个该类型的唯一值。每个 case 都有 ->name；只有 backed case 才有 ->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);

只要值会离开程序（数据库列、URL、表单字段、JSON），就选 backed 枚举。只在代码内部存在的值，比如解析器的状态，选纯枚举。

用 from() 和 tryFrom() 转换值

backed 枚举有两个静态方法，可以把存储的值转换回 case。遇到未知值时，from() 抛出 ValueError；tryFrom() 返回 null，很适合配合 ?? 设置默认值：

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

对用户发来的任何数据用 tryFrom()；对你自己的代码写入的值用 from()，这时出现未知值就说明有 bug，你会希望被告知。参数遵循普通的参数类型规则：对 int 枚举，在默认模式下 Priority::from('5') 返回 Priority::Normal，因为 '5' 会先被转换成 5；Priority::from('5x') 会产生 TypeError；而在 declare(strict_types=1) 下，任何字符串都会产生 TypeError。tryFrom() 也一样：Priority::tryFrom('abc') 会直接抛出异常，而不是返回 null，所以对 int 枚举，要先用 filter_var($raw, FILTER_VALIDATE_INT) 检查表单输入。

用 cases() 列出所有 case

Enum::cases() 按声明顺序返回包含所有 case 的数组。用它可以生成下拉菜单、校验列表，或者配合 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>';

运行它，选一个套餐并点击 Choose：同一个脚本会带着填好的 $_POST['plan'] 再运行一次，tryFrom() 会把提交的字符串转换回 Plan 的 case。伪造的值（比如 plan=gold）会得到 null，也不会有选项被选中。

枚举的方法、常量和接口

枚举可以有方法、静态方法和常量，也可以实现接口。在方法内部，$this 就是当前的 case，所以 match ($this) 是给每个 case 附加数据的自然方式。枚举不能有属性：每个 case 的数据都通过方法提供。

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

在 match 中使用枚举

match 用 === 比较，而枚举的 case 只与自身全等，所以 match 和枚举是天然的搭配。如果你漏写了一个 case，而这个 case 又进入了 match，PHP 会抛出 UnhandledMatchError，而不是悄悄地什么都不返回：

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

match 与 switch 的区别见 match。

枚举与 JSON、字符串

json_encode() 把 backed case 编码为它的值。纯枚举无法编码，而对任何 case 使用 echo 都会失败，因为枚举是对象，不是字符串。应改为输出 ->value 或 ->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; 会抛出 Error（"Object of class Role could not be converted to string"），而且枚举不能实现 __toString()。反过来读取时，JSON 给出的是普通字符串，所以要像上面那样用 from() 或 tryFrom() 转换。编码的更多内容见 json_encode。

使用枚举的常见错误

有三种错误反复出现：case 永远不等于它的值，case 不能作为数组键，new 不能用于枚举：

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

如果需要一个以 case 本身为键的映射，用 SplObjectStorage 或 WeakMap，它们接受对象作为键。