PHP 8.2 BackedEnum 如何接收表单值：tryFrom、校验与默认分支

后台筛选页把订单状态交给 PHP 处理时，表单里的 status=paid 只是一个字符串。直接把它塞给枚举，非法值、空字符串和默认状态很快就会混在一起。更稳妥的做法是让 BackedEnum::tryFrom() 负责“能不能映射”，让业务代码再决定返回 422、使用默认值，还是继续查询。

表单值为什么不能直接当成订单状态

假设筛选接口接收 GET /orders?status=paid。请求参数可能是 paid、空字符串、拼写错误的 paied，也可能根本没有 status。它们在业务上不是同一件事：没有参数表示“不筛选”，空字符串往往表示前端控件传错，非法单词则应当明确提示。

PHP 8.1 起可以定义 backed enum，PHP 8.2 项目中照样可以使用。下面这个枚举把数据库里的稳定值放在 case 右侧，展示名称则留在业务层：

先把 tryFrom 变成输入校验门

tryFrom() 接收整数或字符串，匹配到 case 就返回枚举实例，匹配不到就返回 null。这正好适合处理来自 URL、表单和 JSON 的外部输入：

 'status 不是有效的订单状态']);
        exit;
    }
}

// $status 是 OrderStatus|null，可以安全交给查询层

这里特意先判断 null 和空字符串，再调用枚举映射。这样“没有传筛选条件”和“传了一个无法识别的值”不会被压成同一条路径。

tryFrom、from 和默认分支应该各自负责什么

三种写法看起来只差一个方法名，失败语义却完全不同。接口边界上更适合使用 tryFrom()；当数据已经由数据库约束或前置校验保证合法时，from() 可以让异常尽早暴露。

不要为了让页面“总有结果”而无条件写 ?? OrderStatus::Pending。这会把用户传入的拼写错误伪装成待支付订单，排查数据时很难发现。

整数 backed enum 要先处理表单的字符串类型

如果枚举声明为 int backing type，表单提交的数字通常仍以字符串抵达。不要只看浏览器里填的是数字，就假定 PHP 已经完成了类型转换。可以把允许的原始形式写清楚，再调用 tryFrom()：

是否接受 "01"、带空格的数字或 JSON 数字，要按接口契约决定。枚举只负责映射 case，不替你定义输入清洗规则。

把失败处理接到接口响应而不是异常黑洞

在控制器里，推荐把“读取原始值、映射、错误响应”留在边界层，服务层接收 OrderStatus|null。这样 SQL 构造不会再次处理拼写错误，测试也能分别覆盖缺省、合法和非法三条路径。

function readOrderStatus(array $input): ?OrderStatus
{
    if (!array_key_exists('status', $input) || $input['status'] === '') {
        return null;
    }

    $status = is_string($input['status'])
        ? OrderStatus::tryFrom($input['status'])
        : null;

    if ($status === null) {
        throw new InvalidArgumentException('invalid order status');
    }

    return $status;
}

如果项目已经有统一的请求验证器，就让验证器产生字段错误，再把合法值转换成枚举；不要在多个控制器里复制一套默认值。日志里可以记录原始字段名和错误类型，但不要把完整的 Cookie 或授权头写进去。

常见问题

tryFrom 找不到值会抛异常吗？

不会。对 backed enum 来说，找不到匹配 case 时返回 null；需要异常语义时才使用 from()。

没有 status 参数和非法 status 应该一样处理吗？

通常不一样。前者可以代表不筛选，后者应返回字段错误；只有业务明确允许时才给非法输入设置默认状态。

可以直接把数据库里的整数传给 tryFrom 吗？

可以，但要确认它确实是整数 backed enum 的合法 backing value。对外部输入仍建议先做类型和格式检查，避免把字符串清洗问题藏在映射调用里。

最后检查这三个边界

上线前至少补三组测试：缺少字段时查询范围是否正确，合法 backing value 是否映射到预期 case，非法值是否返回明确的 4xx 错误。只要这三条路径分开，BackedEnum 就能成为输入边界上的小型状态门，而不是新的异常来源。