枚举

枚举（enumeration） 是由程序声明的一组有限合法值。在PHP 8.1及以后，enum声明会创建真正的类型，不是装着常量的普通类，也不是字符串取值的命名约定。参数声明为OrderStatus后，调用方只能传入该枚举的case，不能传入内容碰巧相同的字符串。

每个 枚举case（enum case） 都是该枚举类型的单例对象。两次读取OrderStatus::Paid得到的是同一个case，可以用===比较。case还能作为match的条件、传给带类型的函数，并实现枚举定义中的方法。

枚举适合描述集合由代码拥有、成员彼此排斥的概念，例如订单状态、命令类型或部署环境。它把非法状态挡在类型边界之外，也让IDE和静态分析器看见全部候选值。数据库行、JSON或表单仍只提供标量值，因此这些边界必须先完成解析，之后才能获得这种保证。

集合如果需要由插件扩展，或者多个选项可以同时成立，枚举通常不是合适的模型。插件注册表是开放集合；权限组合更像集合或位标志。把这类概念硬塞进单一枚举，往往会产生不断膨胀的case和难以解释的组合状态。

PHP有两类枚举。纯枚举（pure enum）只声明case名称； 带值枚举（backed enum） 为每个case显式绑定唯一的string或int。只有需要数据库、消息或API往返时才需要backing value。

枚举带来的是 名义类型（nominal typing） 边界。即使两个枚举都有值为'paid'的case，它们仍是两个不同类型，不能互换。这个差别能阻止订单状态误传到发票状态参数中，而普通字符串做不到。

声明与case对象

纯枚举使用enum Name { case Value; }。它的case没有应用定义的标量值，但每个case都有内建的只读name属性，其内容就是源码中的case标识符。name适合诊断和开发工具，不一定适合作为长期外部协议。

带值枚举在名称后写: string或: int，并为每个case写出值。一个枚举不能混用两种backing type，也不能省略某个case的值。backing value必须唯一，PHP不会自动生成连续整数。

带值case还拥有内建的只读value属性。它是你在定义中写下的标量，适合保存到数据库或发到已经约定该表示的API。它不是普通属性，不能重新赋值或通过引用修改。

case是对象，但枚举不允许每个对象携带任意状态。你不能用new创建case，不能克隆case，也不能为枚举声明实例属性或静态属性。枚举没有继承层次：它不能继承类，也不能被类或另一个枚举继承。

UnitEnum与BackedEnum

所有枚举都会自动实现内部接口UnitEnum。它提供静态方法cases()，按声明顺序返回由全部case组成的紧凑数组。枚举不能自行重新定义cases()，普通类也不能手动实现UnitEnum。

带值枚举还会自动实现BackedEnum。该接口提供from()和tryFrom()，两者都按backing value查找，不按case的name查找。返回的仍是已有的单例case，不是新建对象。

from()找不到值时抛出ValueError。当值来自可信数据库，而且未知值意味着数据或部署不一致时，这种立即失败很合适。tryFrom()找不到值时返回null，适合需要生成校验错误的外部输入边界。

在declare(strict_types=1)下，字符串带值枚举的转换方法要求字符串，整数带值枚举则要求整数。不要依赖弱类型调用把输入碰巧转换为backing type。先验证原始表示，再用准确类型调用转换方法，边界政策会更清楚。

方法、接口与Trait

纯枚举和带值枚举都可以声明实例方法、静态方法与常量。实例方法中的$this指向当前case，因此match ($this)可以为每个case给出行为。和普通对象一样，枚举也可以实现一个或多个接口。

接口让调用方依赖行为，而不必依赖某个具体枚举。若OrderStatus与普通类都实现Labelled，接收Labelled的函数可以处理两者。case集合仍由各自的枚举类型封闭，接口不会把不同枚举的case混成一种值。

枚举可以使用Trait，但Trait不能包含属性。只提供方法、静态方法或常量的Trait可以复用；带属性的Trait用在枚举中会造成致命错误。复用之前仍要判断行为是否真的属于所有使用方，通用的values()助手往往只适用于带值枚举。

枚举不能声明构造函数或析构函数，大多数魔术方法也不允许。这个限制保证case没有各自变化的对象状态。需要运行时数据的领域对象应保存枚举属性，而不是把数据塞进枚举本身。

match与完整分支

match使用全等比较，因此枚举case很适合作为匹配条件。省略default后，如果运行时出现没有分支的case，PHP会抛出UnhandledMatchError。这是一种运行时保护，不是PHP编译器提供的穷尽性证明。

新增case时，声明本身仍可以正常加载。只有执行到缺失分支，或静态分析工具检测到它时，问题才会暴露。对必须随case集合更新的领域决策，通常应省略default，并为每个case建立覆盖测试。

某些转换确实有合理的默认结果，例如所有未知显示颜色统一为灰色。但默认分支也会吞掉后来新增的case。使用它之前，应能说明为什么新case自动继承该行为不会造成业务错误。

以下四个示例依次展示纯枚举、标量边界转换、带行为的状态枚举，以及通用枚举代码。输出均由本地PHP 8.3.33 CLI实际生成。

枚举封闭的一组时段

DeliveryWindow是纯枚举。函数签名排除了任意字符串，cases()则给出声明中的全部选项。

cases()保留声明顺序，所以输出与源码排列一致。cutoffHour()没有default；以后新增时段后，测试若遍历全部case，就会执行到缺失分支并失败。

这里的name只是为了输出标识符。若客户界面需要可翻译文本，应使用独立的翻译键或展示层映射，不要把源码标识符直接当作面向用户的文案。

从外部值恢复case

InvoiceState是字符串带值枚举。示例对可能无效的数据使用tryFrom()，对本应有效的数据演示from()的失败方式，并观察带值枚举的默认JSON表示。

<?php

declare(strict_types=1);

enum InvoiceState: string
{
    case Draft = 'draft';
    case Sent = 'sent';
    case Paid = 'paid';
}

foreach (['draft', 'paid', 'refunded', 'PAID'] as $raw) {
    $state = InvoiceState::tryFrom($raw);
    printf("%s => %s\n", $raw, $state?->name ?? 'invalid');
}

try {
    InvoiceState::from('refunded');
} catch (ValueError $error) {
    echo $error::class, PHP_EOL;
}

echo json_encode(InvoiceState::Paid, JSON_THROW_ON_ERROR), PHP_EOL;

draft => Draft
paid => Paid
refunded => invalid
PAID => invalid
ValueError
"paid"

查找按value严格区分大小写，因此'PAID'不会匹配'paid'。是否允许大小写、空白或别名属于输入协议；如需规范化，应在调用tryFrom()前明确完成，而不是把模糊转换藏在枚举内部。

最后一行表明带值枚举会默认编码为其标量值。对JSON对象中的枚举属性也采用同一规则。JSON_THROW_ON_ERROR让编码错误成为异常，避免调用方忽略false。

把状态转换放在枚举旁边

状态允许的下一步与当前case紧密相关，可以由实例方法表达。接口则规定每个状态都必须提供标签行为。

<?php

declare(strict_types=1);

interface Labelled
{
    public function label(): string;
}

enum OrderStatus: string implements Labelled
{
    case Created = 'created';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Cancelled = 'cancelled';

    public function label(): string
    {
        return ucfirst($this->value);
    }

    public function canMoveTo(self $next): bool
    {
        return match ($this) {
            self::Created => in_array($next, [self::Paid, self::Cancelled], true),
            self::Paid => in_array($next, [self::Shipped, self::Cancelled], true),
            self::Shipped, self::Cancelled => false,
        };
    }
}

$current = OrderStatus::Created;
foreach ([OrderStatus::Paid, OrderStatus::Shipped, OrderStatus::Created] as $next) {
    $allowed = $current->canMoveTo($next);
    printf("%s -> %s: %s\n", $current->label(), $next->label(), $allowed ? 'yes' : 'no');
    if ($allowed) {
        $current = $next;
    }
}

Created -> Paid: yes
Paid -> Shipped: yes
Shipped -> Created: no

方法只判断两种case之间是否允许转换，没有修改共享对象。调用方在得到true后更新自己的$current，所以状态所有权仍然清楚。真实系统通常还要在事务中检查当前数据库版本，枚举方法本身不能防止并发写入。

in_array()的第三个参数使用true。case本来就是对象，严格比较能准确表达意图，也避免后来把列表改成标量时悄悄引入弱比较。

在通用代码中缩小枚举类型

接收UnitEnum的函数既可能拿到纯枚举，也可能拿到带值枚举。先检查BackedEnum，才能安全读取value。

<?php

declare(strict_types=1);

enum AccessMode
{
    case Read;
    case Write;
}

enum ResponseKind: int
{
    case Success = 200;
    case Missing = 404;
}

function describeCase(UnitEnum $case): string
{
    if ($case instanceof BackedEnum) {
        return "{$case->name}={$case->value}";
    }
    return $case->name;
}

foreach ([AccessMode::Read, ResponseKind::Missing] as $case) {
    printf("%s: %s\n", $case::class, describeCase($case));
}

var_export(enum_exists(ResponseKind::class));
echo PHP_EOL;

AccessMode: Read
ResponseKind: Missing=404
true

$case::class返回具体枚举的类名，而describeCase()只依赖内部接口。enum_exists()检查名称是否指向已经定义或可自动加载的枚举；它不能替代具体业务允许列表。

这种通用函数适合诊断、表单构建器或框架适配层。领域逻辑通常应接收AccessMode或ResponseKind，否则签名会接受过多无关枚举，并把错误推迟到函数体中。

把标量当作枚举

枚举的价值正来自具体类型边界。若领域函数继续接收string，合法值集合仍靠注释和人工验证维持，类型系统无法阻止拼写错误或错误领域的值。

修复方法： 在边界校验原始类型和格式，再调用tryFrom()；内部不变量被破坏时使用from()立即失败。转换完成后只传递OrderStatus，写出边界错误时保留原始字段和值。

把无效输入静默改成默认case

这种回退看似稳健，却会制造错误业务事实。特别是在多版本服务之间，较新服务发送的case可能被旧服务当成默认状态，导致错误通知或状态倒退。

修复方法： 分别定义字段缺失与值无效的政策。可选字段可以在转换前保留null；无效字段应生成明确校验错误。只有协议明确规定未知值采用默认语义时，才使用回退，并为该行为编写测试。

混淆name与value

把name持久化，会让PHP标识符意外成为数据库契约；用value做开发日志，又可能丢失源码名称。纯枚举根本没有value，所以接收UnitEnum的通用助手不能无条件访问它。

修复方法： 明确每个边界需要源码标识、外部标量还是用户文案。持久化带值枚举的value，诊断时可使用name；展示文本放在翻译层。通用代码先用instanceof BackedEnum缩小类型。

用default掩盖新case

PHP不会在编译时检查枚举match是否穷尽。没有default时，遗漏只会在该case真正执行后抛出UnhandledMatchError；有默认分支时，连这个信号也消失了。

修复方法： 对必须逐case决策的逻辑省略default，并让参数化测试遍历cases()。静态分析可以更早报告遗漏，但测试仍要验证每个case的具体结果。

把封闭集合当作扩展机制

同样，一个枚举变量一次只能持有一个case。把ReadWriteExecute等每种权限组合都做成case，会让组合数量快速增加，而且调用方难以查询单项能力。

修复方法： 开放集合使用接口加注册表；可组合能力使用集合、值对象或经过清楚设计的位标志。只有成员由当前代码库控制，而且未知成员应被拒绝时才使用枚举。

随意修改持久化表示

JSON对带值枚举保存value，PHP的serialize()则记录枚举类型名与case名。两种格式依赖的标识不同。重命名看似只是清理源码，实际可能需要协议版本、数据迁移或兼容读取。

修复方法： 把已发布的backing value当作外部契约，并盘点所有写入格式。先部署能读取旧值与新值的代码，再迁移存量数据，最后停止写旧值；不要把长期跨服务协议建立在PHP序列化格式上。

• PHP手册：基础枚举
• PHP手册：带值枚举
• PHP手册：列出枚举值
• PHP手册：枚举方法
• PHP手册：枚举与对象的区别
• PHP手册：枚举序列化