企业官网建设流程全解析

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

导读

new.interface是 PHPStan 静态分析工具报告的错误标识符（Error Identifier），当代码中尝试使用new关键字实例化一个 PHP 接口时触发。本文将以 website/errors/new.interface.md 文档为骨架，结合仓库中的错误标识符生成规范（website/errors/CLAUDE.md）与标识符映射表（website/src/errorsIdentifiers.json），完整讲解该错误的触发场景、底层原理、修复方式，以及它与其他new.*系列标识符（如new.deprecatedInterface、new.internalInterface）之间的关系。

该错误的定位：new.*前缀从何而来

在 PHPStan 的标识符体系中，new.interface属于new前缀家族。根据 website/errors/CLAUDE.md 中的「Identifier prefix reference」表格，new前缀对应new ClassName()实例化表达式，即只有代码中出现new关键字时，才会产生此类标识符。同一前缀下还包含new.deprecatedClass、new.deprecatedInterface、new.internalInterface、new.notFound等同族错误。

从仓库的标识符映射表 website/src/errorsIdentifiers.json（第 11766 行附近）可以看到，new.interface由核心规则类PHPStan\Rules\Classes\InstantiationRule报告——该规则专门负责分析所有new表达式是否合法，接口实例化是它重点拦截的场景之一。ignorable: true表明该错误可以通过 PHPDoc 注释或配置文件进行忽略（ignore）。

触发示例：一份必然报错的代码

原文档给出了最小触发示例。以下代码会在 PHPStan 分析时被标记为new.interface：

<?php declare(strict_types = 1); interface LoggerInterface { public function log(string $message): void; } $logger = new LoggerInterface();

关键点：

• 文件以<?php declare(strict_types = 1);开头，启用严格类型模式，这是 PHPStan 官方错误示例文档的标准写法（见 website/errors/CLAUDE.md 的 Code example 规范）；
• LoggerInterface只声明了方法契约log(string $message): void，没有任何方法实现；
• 第 17 行new LoggerInterface()尝试直接创建接口的实例，这正是触发点。

从源码结构可以推断，InstantiationRule在分析new表达式时会先解析目标类型，若目标类型是接口（interface），则直接报告new.interface，因为接口在任何情况下都不存在合法的实例化路径。

为什么会被报告：PHP 语言层面的根本原因

原文档给出的核心解释是：

PHP interfaces cannot be instantiated. An interface defines a contract that classes must implement, but it does not provide concrete implementations of its methods. Attempting to usenewwith an interface name will result in a fatal error at runtime.

翻译过来即：PHP 接口不能被实例化。接口只定义了一套「契约」（contract），约定实现类必须提供哪些方法签名，但它自身不包含任何方法的实际实现。因此对接口执行new，在运行时必然触发致命错误（fatal error）。

具体可以从两个层面理解：

1. 运行时层面：如果这段代码真的被执行，PHP 引擎会直接抛出致命错误（类似Cannot instantiate interface LoggerInterface），程序中断，后续代码全部无法运行。也就是说，这不仅是「不推荐」的写法，而是必然崩溃的写法。
2. 语义层面：接口中只有方法签名没有方法体。即使允许实例化，调用$logger->log(...)时也无任何实现可执行，接口对象在概念上就是不完整的对象。PHPStan 的目标是「在不运行代码的情况下发现 bug」，因此在静态分析阶段就将其拦截，避免错误留到运行时才暴露。

这也解释了为什么new.interface属于「代码会崩溃 / 根本不会按预期执行」这一类错误——PHPStan 报告它，是因为这段代码无论怎么执行都不可能成功。

如何修复：实例化实现接口的具体类

修复思路非常直接：不要实例化接口，而是实例化一个实现了该接口的具体类。原文档给出的修复方案如下：

<?php declare(strict_types = 1); -$logger = new LoggerInterface(); +$logger = new FileLogger();

其中FileLogger是一个实现了LoggerInterface的类，例如：

<?php declare(strict_types = 1); class FileLogger implements LoggerInterface { public function log(string $message): void { file_put_contents('/var/log/app.log', $message . PHP_EOL, FILE_APPEND); } }

修复后的调用链变为：new FileLogger()创建的是有完整实现的真实对象，$logger->log(...)能够正常工作。同时，由于FileLogger实现了LoggerInterface，变量可以安全地赋值给LoggerInterface类型的参数或属性，接口的契约价值依然得到保留。

更符合工程实践的修复模式

在实际项目中，直接写死具体实现类虽然能消除new.interface错误，但会牺牲接口解耦的意义。更常见的做法是通过依赖注入（DI）或工厂来获取实现：

<?php declare(strict_types = 1); final class LoggerFactory { public static function create(string $driver): LoggerInterface { return match ($driver) { 'file' => new FileLogger(), 'console' => new ConsoleLogger(), default => throw new \InvalidArgumentException('Unknown logger driver: ' . $driver), }; } } // 使用时 $logger = LoggerFactory::create('file');

这样既满足 PHPStan 的类型检查，又保持了面向接口编程的灵活性。

修复优先级：遵循 PHPStan 官方文档的修复顺序

根据 website/errors/CLAUDE.md 的「How to fix it」规范，修复此类错误应遵循以下优先级顺序：

1. 修复真正的 bug——即把new的目标从接口换成具体实现类，这是本文场景的唯一正确修复；
2. 用原生 PHP 类型声明收窄类型；
3. 用 PHPDoc 类型（@param、@return、@var）收窄类型；
4. 在函数体内通过类型收窄逻辑处理；
5. 如果规则本身可配置，再考虑通过配置调整 PHPStan。

对于new.interface而言，前 4 步都不适用（接口实例化不存在「类型收窄」的余地），唯一正确的做法就是第 1 步：替换为具体实现类。因此它也是最简单、最直接的错误类型之一。

与相关标识符的区分：deprecated 与 internal 变体

new.interface不是孤立的，它与new前缀下的其他接口相关标识符容易混淆。仓库中已有两份关联文档可以对照阅读：

new.deprecatedInterface（已废弃接口的实例化）

见 website/errors/new.deprecatedInterface.md。该标识符由phpstan-deprecation-rules扩展报告，针对的是代码中实例化了一个被@deprecated标记的接口：

/** @deprecated Use NewInterface instead */ interface OldInterface { } $x = new OldInterface();

该文档特别指出一个关键事实：触发这个标识符本身就要求实例化接口，而 PHP 不允许这样做，因此 PHPStan 总会同时报告一个new.interface错误；在实践中，new.deprecatedInterface反而不会单独出现。换句话说，new.interface是更底层的「硬错误」，new.deprecatedInterface是在其之上的「附加信息」。

new.internalInterface（内部接口的使用）

见 website/errors/new.internalInterface.md。该标识符由RestrictedInternalClassNameUsageExtension（new.internalClass等标识符的同一套内部标签机制）报告。该文档同样明确指出：

In practice, this is typically reported as Cannot instantiate interface (new.interface) because interfaces cannot be instantiated at all.

即：由于接口根本无法实例化，这类访问内部接口的代码在实际分析中通常也会落回new.interface这条更通用的错误路径上，new.internalInterface只在「内部访问违规」是主要关注点时才被报告。

三者的关系小结

补充：为什么new.interface可被忽略（ignorable）

文档 Frontmatter 中ignorable: true表明该错误允许被忽略。虽然接口实例化在任何时候都是错误的，但 PHPStan 仍将其设计为可忽略类型，原因包括：

• 部分代码库可能通过代码生成、运行时动态代理等机制间接「实例化」接口（尽管标准 PHP 无法做到），此时团队需要抑制该报告；
• 在渐进式引入 PHPStan 的过程中，团队可能希望先集中处理更严重的错误，暂时将此类问题放入 baseline。

忽略方式与 PHPStan 其他错误的忽略机制一致，例如在 phpstan.neon 中配置ignoreErrors，或在代码中使用@phpstan-ignore注释（具体可参考 website/errors/CLAUDE.md 中「Suggest ignoring the error (the detail page already covers that)」的说明——错误详情页本身已涵盖忽略方法，因此文档正文不再赘述）。

需要留意的是：并非所有标识符都可忽略，ignorable: false的标识符（使用->nonIgnorable()构建，或前缀为phpstan.、phpstanPlayground.）是强制报告的，new.interface不在其列。

如何在自己的项目中定位并复现

要验证这个错误，可以在当前仓库的 e2e 测试目录之外任意创建一个测试文件，或直接复用本文的示例代码，然后运行 PHPStan：

# 在当前仓库根目录下执行，分析示例文件 php phpstan analyse path/to/your-file.php --error-format=table

输出中会显示错误消息（类似Cannot instantiate interface LoggerInterface）以及对应的错误标识符new.interface。若希望输出中直接显示标识符列，可使用：

php phpstan analyse path/to/your-file.php --error-format=raw

或结合--error-format=json查看结构化输出中的identifier字段。这是确认错误标识符、并将其用于 CI 忽略规则或 baseline 管理的第一步。

小结

• new.interface由核心规则InstantiationRule报告（见 website/src/errorsIdentifiers.json 中第 11766 行起的映射），对应new前缀下的接口实例化场景；
• 触发原因本质上是 PHP 语言规则：接口只有契约、没有实现，运行时必然致命错误；
• 唯一正确修复是实例化实现了该接口的具体类，配合依赖注入/工厂模式可以兼顾类型安全与解耦；
• 它与new.deprecatedInterface、new.internalInterface属于同族错误，但后两者在实际分析中通常会落回new.interface，因为接口根本无法实例化；
• 该标识符ignorable: true，可按需通过 ignore 机制或 baseline 忽略。

如需继续深入，可阅读本仓库中new前缀系列的其他标识符文档（website/errors 目录下的new.*.md文件），以及错误标识符文档的整体生成与写作规范 website/errors/CLAUDE.md。

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