企业官网建设流程全解析

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

PHP 8.1 引入的枚举（enum）是语言层面的“预定义单例”，不允许通过new关键字创建实例。本文以 PHPStan 的错误标识new.enum（Cannot instantiate enum）为主线，结合仓库中该错误标识的官方文档 website/errors/new.enum.md 与源码映射关系，完整讲解该错误的触发代码、底层原因、修复方式，以及它与new.interface、new.deprecatedEnum、new.internalEnum等相邻标识的区别。读完本文，你将能准确识别这类错误、用枚举 case 正确替换new调用，并在 PHPStan 配置中按标识精确忽略或排除误报。

一、错误标识new.enum是什么

new.enum是 PHPStan 内部使用的错误标识（error identifier），其官方定义为：

"Enums cannot be instantiated with the new keyword."（枚举不能使用new关键字实例化。）

在仓库的 website/src/errorsIdentifiers.json 中，new.enum被映射到核心规则类PHPStan\Rules\Classes\InstantiationRule（位于 phpstan-src 的 src/Rules/Classes/InstantiationRule.php 对应行号附近），也就是说它由 PHPStan 核心的“实例化检查规则”直接报告，而不是任何第三方扩展。

与所有new.*系列标识一样，new.enum在文档 front matter 中标记为ignorable: true，意味着它可以被列入 baseline 或通过ignoreErrors精确忽略（详见下文“如何按标识忽略”一节）。

二、触发该错误的代码示例

文档 website/errors/new.enum.md 给出的触发示例非常简洁：

<?php declare(strict_types = 1); enum Suit { case Hearts; case Diamonds; case Clubs; case Spades; } $suit = new Suit(); // error: Cannot instantiate enum Suit.

执行 PHPStan 分析时，第 13 行new Suit()会被报告为Cannot instantiate enum Suit.，对应标识new.enum。

这个例子同时也说明一个关键点：PHPStan 的规则检查针对的是静态代码分析阶段——即使这段代码永远不会真正执行到new Suit()一行，PHPStan 依然会在分析时报告错误，因为语言层面已经决定了该写法必然非法。

三、为什么会报告这个错误

从语言语义层面看，原因如下（文档“Why is it reported?”一节）：

• PHP 中的枚举不允许使用new关键字实例化；
• 枚举 case 是预定义的单例实例，必须直接通过 case 名称访问，例如Suit::Hearts；
• 尝试对枚举执行new，在运行时（如果代码被真正执行）将直接触发致命错误（fatal error）。

从 PHPStan 的实现层面看，该检查由核心规则类InstantiationRule负责。从源码结构可以推断：InstantiationRule在遇到new表达式时会解析目标类型的性质——当解析出的类型是枚举（enum）时，规则判定该实例化操作非法并报告错误。这与同一规则家族中其他new.*标识（如new.interface报告接口不可实例化）的判定逻辑是一致的，都是围绕“目标类型是否允许实例化”这一核心问题展开。

3.1 与new.interface的异同

两者都属于“类型不允许被new”的范畴，但对象不同：

• new.interface：接口（interface）只是契约，没有具体实现，new一个接口必然致命错误，对应文档 website/errors/new.interface.md；
• new.enum：枚举的 case 是预定义单例，不存在“构造”的概念。

修复思路也因此不同：接口需要改实例化一个实现了该接口的具体类（如new FileLogger()），而枚举则需要改用其 case（如Suit::Hearts）。

3.2 与new.deprecatedEnum、new.internalEnum的关系

仓库中还收录了两个与枚举实例化相关的特殊标识，它们在实际使用中有很强的“叠报”特征：

• new.deprecatedEnum（见 website/errors/new.deprecatedEnum.md）：由 phpstan-deprecation-rules 扩展报告，针对@deprecated枚举出现在new表达式中的情况。文档明确注明：要触发该标识必须实例化枚举，而 PHP 本身不允许这样做，因此 PHPStan 总是会同时（甚至优先）报告new.enum，在实践中该废弃标识实际上不会被单独报告。
• new.internalEnum（见 website/errors/new.internalEnum.md）：针对@internal枚举在包外部被用于实例化上下文的情况，文档同样注明：实践中通常会报告为new.enum，只有在内部访问违规是首要关注点时才会报告new.internalEnum。

这两个文档共同揭示了 PHPStan 错误报告的一个设计特征：当一次new同时违反“语言规则”和“元信息规则”（废弃/内部标记）时，PHPStan 优先报告语言层面必然错误的new.enum，其余标识更多是理论上的触发路径。

四、如何修复

修复方式很直接——放弃实例化，直接使用枚举 case：

-$suit = new Suit(); +$suit = Suit::Hearts;

结合仓库中相邻错误文档的修复示例，可以归纳出枚举使用的通用写法：

// 正确：通过 case 名称直接访问预定义单例 $suit = Suit::Hearts; $suit = Suit::Clubs; // 正确：使用 match / switch 基于 case 进行分支 $name = match ($suit) { Suit::Hearts => 'hearts', Suit::Diamonds => 'diamonds', Suit::Clubs => 'clubs', Suit::Spades => 'spades', };

如果业务逻辑需要的是“某种默认/回退值”，也应通过 case 或枚举自带的方法（如from()/tryFrom()，针对 backed enum）来获取，而不是试图构造枚举实例。

五、如何按标识忽略或纳入 baseline

由于new.enum的ignorable为true，你可以在phpstan.neon中按标识精确处理：

parameters: ignoreErrors: - identifier: new.enum message: '#Cannot instantiate enum#'

或者使用--generate-baseline将此类错误沉淀为 baseline：

vendor/bin/phpstan analyse --generate-baseline

生成的 baseline 会以标识级别记录该类错误，后续新出现的同类问题仍会报告，从而实现“存量豁免、增量拦截”。

需要注意：从仓库文档约定（website/errors/CLAUDE.md）可以得知，只有ignorable: true的标识才能被忽略，而new.enum明确满足这一条件，因此上述配置是合法可用的。

六、官方文档在仓库中的组织方式

new.enum的说明文档位于 website/errors/new.enum.md，属于 PHPStan 官网“错误标识”文档体系的一部分。该目录下的每一份文档都遵循统一结构（front matter + 代码示例 + 原因说明 + 修复方式），并通过 website/src/errorsIdentifiers.json 将每个标识映射到产生它的规则类与源码位置。以new.enum为例，该 JSON 明确记录了其来源为PHPStan\Rules\Classes\InstantiationRule，这让开发者可以沿“标识 → 规则类 → 源码实现”的链路深入排查规则行为。

七、小结

一句话记住这个错误：在 PHP 里枚举没有“构造函数”，只有预定义好的 case；把new Suit()换成Suit::Hearts，即可同时消除静态分析错误和潜在的运行时致命错误。

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