PHP 枚举（Enum）实战：告别魔法数字的状态管理方案

PHP 枚举（enum）是消灭「魔法数字」最干脆的方案：状态用 `enum PostStatus: int` 定义一次，读写用 `->value` 和 `tryFrom()`，分支用 `match`，从此再也不会有人问「status = 3 到底是删除还是关闭」。唯一的硬前提是 PHP 8.1+ —— 而 Clara BBS 官方支持 PHP 7.4-8.5，所以在写插件时这条红线必须先考虑。

为什么魔法数字必须换掉

结论：魔法数字的真正成本不在「看不懂」，而在「改不动」。

一个典型的论坛里，帖子状态可能散落在十几个地方：模板里写 `if ($post['status'] == 1)`、审核逻辑里写 `$status = 2`、回收站恢复时写 `status <> 4`。等到要加一个「待审核」状态，你得全站 grep，还得靠肉眼判断哪个 `2` 是帖子状态、哪个 `2` 是用户组 ID。

换成枚举后，状态只有一处定义，IDE 能跳转、能补全、能静态检查，常量改名时全项目一起变。这是纯收益，没有副作用。

最小改造：从 int 到 BackedEnum

结论：存量项目不用大改，把「定义」和「关键分支」两处换成枚举即可，其余代码继续按 int 走。

第一步，定义带后端的枚举（BackedEnum 指每个 case 绑定一个标量值，便于直接存数据库）：

enum PostStatus: int
{
    case Draft   = 0; // 草稿
    case Pending = 1; // 待审核
    case Live    = 2; // 已发布
    case Closed  = 3; // 已关闭
    case Trash   = 4; // 回收站
}

第二步，入库出库各一层转换。出库用 `tryFrom()`，因为数据库里可能存在历史脏值：

$status = PostStatus::tryFrom((int)$row['status']) ?? PostStatus::Live;

入库直接 `$status->value`。注意这里要用 `tryFrom` 而不是 `from`——`from` 遇到非法值会抛 `ValueError`，在列表页遍历几百条数据时很容易炸。结论：读取数据库字段一律用 tryFrom + 兜底默认值，写入时才用 from。

第三步，分支改写。`match` 是严格比较（`===`），正好和枚举语义对齐：

$visible = match ($status) {
    PostStatus::Live, PostStatus::Closed => true,
    default => false,
};

枚举不是常量集合，它可以带行为

结论：把「标签文案、颜色、是否可见」这类和状态强绑定的逻辑塞进枚举方法里，比在模板里写 if-else 干净一个数量级。

enum PostStatus: int
{
    case Draft = 0;
    // ... 其余 case

    public function label(): string
    {
        return match ($this) {
            self::Draft   => '草稿',
            self::Pending => '审核中',
            self::Live    => '正常',
            self::Closed  => '已关闭',
            self::Trash   => '回收站',
        };
    }
}

模板里只需要 `<?= $post->status->label() ?>`。将来加「高亮色」「是否计入统计」同理，加方法比到处塞条件判断稳妥得多。

要提醒的是枚举有限制：不能有实例属性、不能被 new、不支持继承。需要挂外部数据（比如颜色值从配置读）就实现接口或加静态方法，别指望它变成一个小对象。输出到 JSON 时实现 `JsonSerializable` 返回 `->value`，避免前端拿到 `"Live"` 这种枚举名。

在 Clara BBS 插件里用枚举，先过版本这一关

结论：Clara BBS 正常运行在 PHP 7.4-8.5 上，而 enum 需要 8.1+；7.4 下解析到 enum 语法会直接致命错误，运行时 `PHP_VERSION_ID` 判断救不了它。

原因是语法错误发生在文件被包含的那一刻。所以插件里不能这么写：

// 错误示范：7.4 下这个文件根本加载不了
if (PHP_VERSION_ID >= 80100) {
    enum PostStatus: int { /* ... */ }
}

正确做法是把枚举单独放一个文件，只在版本达标时加载：

if (PHP_VERSION_ID >= 80100) {
    require __DIR__ . '/lib/PostStatus.php';
}

7.4 环境下就走类常量 + 静态方法的降级路径。这和 Clara BBS 插件「放在 content/plugins、运行时钩子加载、保存即生效、无需编译」的机制是兼容的——没有编译缓存，也就不存在缓存里躺着旧枚举的问题，改完保存即生效。

还有一点：新增状态字段走后台「系统工具→数据库升级」的增量 DDL 即可，列类型建议 `tinyint` 而不是 MySQL 的 `ENUM` 类型——枚举定义留在 PHP 侧一处维护，数据库里保持普通整数，加一个状态值不用改表结构。

用枚举描述状态机，收益最大

结论：真正让枚举发光的不是单个状态，而是「哪些状态可以走到哪些状态」的流转规则。

以论坛悬赏为例，业务上有「托管中 → 已采纳 → 已发放」「托管中 → 已取消 → 已退款」这条链路。这些规则如果写成散落的 if，几乎必然出 bug；写成枚举方法就一目了然：

public function canAccept(): bool
{
    return $this === self::Escrowed; // 只有托管中才能采纳
}

同理，「不能采纳自己的回复」「未采纳前才可取消退款」这类约束，放在状态方法里判断，比在控制器里叠三层 if 更容易测、更容易读。状态流转集中到枚举里，接口层只负责报错，业务逻辑就不会漂移。

总结一下落地路径：先用 `enum XxxStatus: int` 定义一次，读库统一 `tryFrom` + 默认值，分支改 `match`，把标签和流转判断收进枚举方法；存量项目只改定义和关键分支，其余照旧。写 Clara BBS 插件时额外记一条——枚举放独立文件、判断 `PHP_VERSION_ID >= 80100` 后再 require，别让 7.4 的站点因为一个语法错误直接白屏。