PHP 枚举怎样把外部字符串映射为 backed case

接口、JSON 或数据库里拿到的通常是 "paid" 这样的字符串，而业务函数希望接收的是一个明确的枚举 case。PHP backed enum 已经为这个转换准备了标准入口：输入可信且非法值应视为程序错误时使用 OrderState::from($raw)；输入来自用户或外部系统时使用 OrderState::tryFrom($raw)，再决定返回错误、默认值或拒绝请求。

官方文档地址：https://www.php.net/manual/en/language.enumerations.backed.php

本文只解决 string-backed enum 的字符串映射，不把框架参数绑定、ORM 转换或数据库迁移混进来。先把输入边界分清，后面的异常处理才不会变成“所有字符串都当成合法状态”。

先确认字符串和 backed case 不是同一个值

backed enum 的每个 case 都有一个显式的标量值。例如 OrderState::Paid 是枚举对象，OrderState::Paid->value 才是字符串 "paid"。外部输入拿到的是后者的文本表示，业务层需要通过 from() 或 tryFrom() 把它映射回前者。

一个 backed enum 只能选择 string 或 int 其中一种 backing 类型；每个 case 都要显式写出唯一值，不会自动生成连续编号。映射成功后得到的是 case 对象，可以继续传给类型声明为 OrderState 的函数；不要把原始字符串直接和 case 对象混用。

根据输入可信度选择 from 或 tryFrom

from(int|string) 找不到对应 backing value 时抛出 ValueError，适合已经完成白名单校验、缺值代表代码或配置错误的场景。tryFrom(int|string) 找不到对应值时返回 null，适合请求参数、Webhook、导入文件和第三方接口等不可信输入。

这两个方法的差别不是“一个更快、一个更安全”，而是失败契约不同。用 tryFrom() 后必须处理空值；用 from() 后必须决定在哪里捕获或转换 ValueError。把 from() 包在宽泛的 catch (Throwable) 里再继续业务流程，会把拼写错误伪装成合法状态。

把非法值、缺省值和类型错误分开处理

外部字符串映射通常有三类结果。第一类是 "paid" 这种已定义值，转换为 OrderState::Paid；第二类是 "pay"、空字符串或未知版本值，转换失败；第三类是调用方传入数组、对象等根本不符合方法参数的值，这属于类型错误，不应和“没有对应 case”混成同一个默认状态。

缺省值也要由业务语义决定。若请求没有传状态，可以在字段缺失时补一个默认字符串，再调用 tryFrom()；若请求明确传了未知字符串，通常应返回参数错误，而不是静默改成 Pending。默认值应该只覆盖“没有提供”，不应覆盖“提供了但不认识”。

在 declare(strict_types=1) 下，方法参数的类型边界更清楚：字符串-backed enum 接受字符串输入；整数、浮点数和其他类型的处理要遵守 PHP 官方文档描述的弱/强类型规则。不要为了让转换“总能成功”而先把所有输入强制转成字符串，这可能把数组、浮点值或格式错误掩盖掉。

完整示例：从请求字符串得到业务 case

下面的示例把请求字段当作不可信输入。没有字段时使用业务约定的 pending；字段存在但不在枚举值集合中时返回参数错误；转换成功后，后续函数只接收 OrderState，不再到处比较字符串。

 'paid'];
$state = stateFromRequest($request);

if ($state === null) {
    throw new InvalidArgumentException('state 不是受支持的枚举值');
}

echo $state->name . PHP_EOL;
echo canShip($state) ? '可发货' : '暂不可发货';

这里的关键不是把字符串包一层函数，而是把边界集中起来：stateFromRequest() 处理缺失字段、类型检查和 tryFrom()；canShip() 只面对明确的 case。若输入来自内部配置且必须有效，可以把转换处改成 OrderState::from($raw)，让配置错误尽早暴露。

发布前用这张清单检查映射契约

• 枚举是明确的 string 或 int backed enum，每个 case 的值唯一且稳定。
• 外部输入优先使用 tryFrom()，并明确处理 null；可信配置才考虑 from()。
• “字段缺失”和“字段存在但非法”走不同分支，默认值不能吞掉拼写错误。
• 转换完成后把 case 传入业务函数，避免在多个地方复制字符串比较。
• 数组、对象、浮点值等类型问题不要伪装成普通的未知 case。

常见追问有两个。第一，能不能直接写 OrderState::Paid 和字符串比较？不建议，case 是对象，外部文本应先走 backed enum 的转换方法。第二，tryFrom() 返回 null 后能不能统一改成 Pending？只有产品明确把未知值当作待处理时才可以；如果未知值意味着调用方传错，应该保留错误信息并拒绝继续。

最终可以把规则压缩成一句话：外部字符串先按 backing value 映射，可信输入用 from()，不可信输入用 tryFrom()；映射失败后是报错、默认还是拒绝，必须由业务契约明确决定。