PHPStan 错误 `enum.missingCase` 全解：Backed Enum 缺少必需值时如何修复

• 开发工具
• 代码质量
• 静态分析

导读

enum.missingCase是 PHPStan 在分析 PHP 8.1+ 枚举（enum）时报告的一条错误，它指出：一个声明了标量 backing type（如string或int）的枚举中，某个 case 缺少必需的值。本文以 enum.missingCase.md 为骨架，结合本仓库的错误标识符映射与相关枚举错误文档，讲解该错误的触发条件、背后的 PHP 语言语义，以及两种修复方案，帮助你彻底理解并消除这类静态分析报错。

一、什么是enum.missingCase？

enum.missingCase是 PHPStan 提供的错误标识符（error identifier）之一，其官方短描述为：

Backed enum case is missing a required value.

它属于enum.*错误族，专门用于检查 PHP 8.1 引入的枚举语法。在该错误的文档 Frontmatter 中，ignorable: false表示这是一个不可通过@phpstan-ignore或 ignoreErrors 轻易忽略的错误——它指向的代码模式（backed enum 的 case 缺少值）在运行时必然引发 PHP 致命错误，属于 PHPStan 优先保证正确性的硬约束类问题。

触发示例

以下代码会触发enum.missingCase：

<?php declare(strict_types = 1); enum Status: string { case Active = 'active'; case Inactive; }

在这个例子中，Status是一个以string为 backing type 的枚举，Active显式赋值为'active'，而Inactive没有赋值，因此 PHPStan 会报告enum.missingCase。

二、为什么会被报告？

PHP 语言语义：backed enum 的每个 case 都必须有值

在 PHP 8.1+ 中，枚举分为两类：

• 纯枚举（pure enum）：声明时不带标量类型（如enum Color {}），其 case 不携带任何值；
• 带值枚举（backed enum）：声明时带有: string或: int标量 backing type，此时每一个 case 都必须提供对应类型的显式值。

enum.missingCase正是针对这条语言约束：当枚举声明了 backing type，却有 case 未赋值时，PHP 运行时本身就会抛致命错误，PHPStan 则在静态分析阶段提前把这个错误报告出来，避免代码在运行期崩溃。

需要强调的是，backed enum 仅支持int或string两种 backing type。如果写成enum Priority: float，则会触发同族的另一个错误 enum.backingType。

实现来源

在本仓库中，该错误的标识符到源码规则的映射记录在 errorsIdentifiers.json：enum.missingCase由 PHPStan 源码仓库（phpstan-src 2.3.x）中的PHPStan\Rules\Classes\EnumSanityRule在src/Rules/Classes/EnumSanityRule.php第 186 行附近报告。EnumSanityRule是 PHPStan 对枚举声明做“一致性检查”（sanity check）的专用规则，同族检查还包括：

• enum.backingType：backing type 不是int或string；
• enum.caseWithValue：纯枚举的 case 却带了值；
• enum.duplicateValue：多个 case 共用了同一个 backing value；
• enum.caseType 与 enum.caseOutsideOfEnum 等其他枚举结构问题。

从这一族错误的整体设计可以看出，PHPStan 把 PHP 语言在枚举上的全部硬性约束都纳入了静态检查范围：值缺失、值重复、类型非法、纯枚举带值、case 越界等，都能在运行前被发现。

三、如何修复？

原文档给出了两种修复思路，分别对应两种不同的代码意图。

方案一：给缺少值的 case 补上值

如果这个枚举本来就是 backed enum，正确做法是为每个 case 提供合法的标量值：

enum Status: string { case Active = 'active'; - case Inactive; + case Inactive = 'inactive'; }

要点：

• 补充的值必须与 backing type 匹配：string类型填字符串字面量，int类型填整数字面量；
• 每个 case 的值必须唯一。若补上的值与已有 case 重复，将触发同族错误 enum.duplicateValue（该错误对应的示例中Low与Critical同为1即被判为重复）。

方案二：若枚举本不需要值，去掉 backing type

如果业务上这些 case 并不需要关联标量值（例如只是作为状态标识符使用），那么正确的建模方式是声明为纯枚举：

-enum Status: string +enum Status { - case Active = 'active'; - case Inactive; + case Active; + case Inactive; }

去掉: string后，枚举变为纯枚举，case 不再需要（也不允许）带值。反过来，如果此时某个 case 仍然写了= 'active'，则会触发同族的 enum.caseWithValue 错误，提示“纯枚举的 case 带了值，只有 backed enum 才能有 case 值”。

四、两种方案的取舍

选择哪一种修复方式，取决于该枚举在代码库中的实际用法：

此外，如果你的枚举需要关联复杂的非标量数据（如浮点数权重），即便保留了 backing type 也不能直接用float（见 enum.backingType），此时可以在 case 上定义方法，用match ($this)返回额外数据。但请记住：case 本身的赋值仍然必须是合法的标量值，enum.missingCase的要求不会因此免除。

五、在本仓库中的相关参考

本仓库（PHPStan）以自身作为分析对象，错误文档目录 website/errors/ 中收录了全套enum.*错误说明，彼此互为补充：

• enum.missingCase.md：本文主题——backed enum 的 case 缺少值；
• enum.backingType.md：backing type 非法（非int/string）；
• enum.caseWithValue.md：纯枚举 case 携带值；
• enum.duplicateValue.md：case 值重复；
• enum.caseType.md、enum.caseOutsideOfEnum.md：case 类型与位置约束。

这些文档均遵循 website/errors/CLAUDE.md 约定的统一格式生成：先给出可触发错误的 PHP 代码示例，再解释 PHP 语言语义层面的原因，最后给出diff-php形式的修复代码。该目录的说明文件还注明，这些文档由 GitHub Actions 工作流读取 errorsIdentifiers.json 中每个标识符对应的规则类与源码位置后自动生成，因此每条错误文档都能追溯到具体的规则实现（如EnumSanityRule），保证了文档与源码行为的一致性和可验证性。

在 e2e 测试目录中也能看到 backed enum 的实际用法样例，例如 e2e/undiscoverable-symbols-2/src/Validator/Enum.php 的 PHPDoc 中就以class-string<\BackedEnum>作为参数类型约束，说明 backed enum 在真实项目（如 Symfony Validator 约束）中是常见的领域建模方式，正确书写其 case 值对静态分析结果的准确性有直接影响。

小结

• enum.missingCase报告的是 backed enum 中 case 缺少必需标量值的问题，这是 PHP 语言层面的硬性约束，运行时必然致命；
• 修复方式二选一：给缺失的 case 补上合法且唯一的标量值，或去掉 backing type 将枚举改为纯枚举；
• 该错误由EnumSanityRule在枚举一致性检查阶段报告（对应 phpstan-src 的src/Rules/Classes/EnumSanityRule.php），与enum.backingType、enum.caseWithValue、enum.duplicateValue等共同构成完整的枚举合法性检查体系；
• 修复时注意与同族错误联动：补值时不能与已有 case 重复，去类型后不能残留 case 值。

• 开发工具
• 代码质量
• 静态分析