PHP backed enum 从请求字符串转换时怎么处理非法值

PHP backed enum 最适合放在“外部字符串已经进入应用、但还没有进入业务判断”的那条边界上。请求里的 pending、paid 可以转换成 OrderState，未知值则应该被明确拒绝，而不是偷偷当成某个默认状态。

先把请求值收敛成合法的 backed enum

下面做一个很小的订单状态接口。枚举值使用字符串，是因为它们会出现在请求参数、日志和 JSON 响应中；case 名称则服务于 PHP 代码内部。两者不要混为一谈：Paid 是 case 名称，paid 才是对外值。

这里的返回类型是 ?OrderState，刻意把“没有合法状态”作为正常分支交给上层处理。tryFrom() 找不到对应 backing value 时返回 null，不会把用户输入直接变成未捕获异常。

from、tryFrom 与 JSON 输出各自负责什么

两个转换方法的分工可以用一张表记住：

例如内部任务已经保证状态来自数据库约束，就可以使用 from()：

 $state], JSON_UNESCAPED_UNICODE);
// 输出：{"state":"paid"}

不要为了“保险”在所有位置都捕获 ValueError 并返回 pending。默认值会把数据问题隐藏起来，尤其是在订单、审批或库存状态中更危险。只有业务真的定义了降级语义，才应该显式写出来。

把转换器接到一个最小 HTTP 响应

把上面的函数放到控制器边界后，业务层只接收合法的 OrderState。非法值不应该继续走订单查询或状态变更：

 'invalid_order_state',
        'allowed' => array_map(fn (OrderState $item) => $item->value, OrderState::cases()),
    ], JSON_UNESCAPED_UNICODE);
    return;
}

// 业务代码拿到的是枚举对象，不需要再次比较原始字符串。
echo json_encode(['state' => $state], JSON_UNESCAPED_UNICODE);

如果项目从 JSON body 读取值，先用 json_decode($body, true) 得到数组，再把字段交给同一个转换函数即可。不要在多个控制器里分别写大小写修正、空值判断和 case 比较，否则后续增加状态时很容易漏改。

上线前用四个边界确认结果

• 传入 pending：得到 OrderState::Pending，JSON 中得到 "pending"。
• 传入 unknown：tryFrom() 得到 null，接口返回 400，不进入业务逻辑。
• 传入空字符串或数组：类型收敛失败，仍然返回 400，不让 TypeError 代替输入校验。
• 内部对 paid 调用 from()：得到 OrderState::Paid；契约错误应保留 ValueError 线索。

最后再记一个容易忽略的点：backed enum 的 value 是只读属性；如果需要展示枚举对外值，读取它即可，不要尝试修改。纯 enum 没有 scalar backing value，不能直接按本例处理。

常见问题

请求参数一定要先 trim 吗？

如果协议允许前后空白被视为无效，就不要 trim；如果表单输入允许无意空格，trim 后再 tryFrom 更符合用户预期。关键是把规则集中在一个边界函数里。

可以直接用 OrderState::from($_POST['state']) 吗？

不建议。请求值不可信，非法值会抛 ValueError，非预期类型还可能触发 TypeError。先检查类型，再用 tryFrom 把失败变成可控的 400 响应。

为什么 JSON 中没有显示 Pending 这样的 case 名称？

backed enum 默认序列化 backing value，所以 OrderState::Pending 会输出 "pending"。如果接口需要另一种结构，应在 DTO 或 JsonSerializable 层明确转换。