PHP Enum backed value 解析失败时怎么返回业务错误

订单状态、支付方式、用户角色这类字段经常来自查询参数或 JSON。它们看起来只是字符串，进入业务层后却需要稳定的类型边界。PHP backed enum 的关键区别是：from() 找不到值会抛出 ValueError，tryFrom() 找不到值则返回 null。面对不可信的外部输入，先用 tryFrom() 判断，再把失败转换成自己的业务错误，通常比直接把底层异常抛给接口调用方更合适。

把“不是合法枚举值”当成输入校验失败处理：边界层调用 tryFrom()，对 null 生成稳定的错误码；只有已经确认可信的内部值，才考虑使用 from()。

from 和 tryFrom 的异常边界先分开

下面的枚举用字符串保存订单状态。数据库或请求体里的 paid 可以还原成 OrderStatus::Paid；refunded 不在枚举定义内，就是一次失败转换。

getMessage();
}

from() 的异常本身没有错，但它更像“调用者承诺这个值一定合法”后的强断言。HTTP 参数、表单字段、消息队列载荷和第三方接口响应都不应默认满足这个承诺。

把外部输入转换成可读的业务错误

不要把 tryFrom() 直接散落在每个控制器里。集中转换可以统一空值规则、错误码和日志字段，领域服务拿到的就只会是合法的 OrderStatus。

这里的异常只是领域层和应用层之间的信号，不代表要把 rawValue 原样返回给用户。日志可以记录经过脱敏的输入，接口响应则使用固定的 order_status_invalid，这样前端和监控都不依赖 PHP 的异常文案。

控制器只做响应映射，领域服务只接收合法状态

控制器捕获自己的业务异常后，可以把它映射为 422 和稳定的 JSON。成功路径则把 enum 交给领域服务，服务不需要再猜测字符串是否有效。

try {
    $status = parseOrderStatus($request->input('order_status'));
    $orderService->changeStatus($orderId, $status);

    return response()->json(['ok' => true]);
} catch (InvalidOrderStatus $error) {
    // 只向客户端暴露稳定的业务码，不泄露原始输入和 PHP 异常信息。
    return response()->json([
        'ok' => false,
        'code' => $error->getMessage(),
    ], 422);
}

如果字段是内部配置、已经过数据库约束或来自代码常量，可以在更靠后的可信路径使用 OrderStatus::from($value)。但即使如此，也要让异常进入统一的错误处理器，避免在生产响应中出现堆栈和实现细节。

常见问题

tryFrom 找不到值时能不能返回默认状态？

可以在明确业务允许时使用 OrderStatus::tryFrom($value) ?? OrderStatus::Pending，但这会把拼写错误和真正缺省混在一起。订单状态通常更适合返回错误，让调用方修正输入。

为什么不直接捕获 ValueError？

可以捕获，但那意味着把“预期的外部校验失败”当成异常路径处理。tryFrom() 能让这个分支显式返回 null，再由业务异常承载稳定语义。

backed enum 的 value 可以重复吗？

不可以。同一个 backed enum 的每个 case 都必须有唯一的标量值，否则类型定义本身就不成立。

资料来源

• PHP 手册：Backed Enumerations：from、tryFrom、ValueError 及 backed value 的规则。
• PHP 手册：Enumerations：枚举类型的基本语义。