企业官网建设流程全解析

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

导读

class.nameCase是 PHPStan 在检测到代码以错误的大小写引用类名时抛出的错误标识符。PHP 运行时本身对类名大小写不敏感，但大小写不一致的引用会损害可读性，并在 Linux 等大小写敏感的文件系统上引发自动加载问题。本文以 website/errors/class.nameCase.md 为骨架，结合仓库中的错误标识符映射表 website/src/errorsIdentifiers.json、配置参考 website/src/config-reference.md 及同族错误文档，完整说明该错误的触发场景、修复方法、底层规则实现与相关配置项，帮助你彻底理解并掌握处理这类报告的正确姿势。

错误概览：frontmatter 中的元信息

每个错误文档的 YAML frontmatter 都携带该标识符的关键元数据。class.nameCase的元信息如下：

关于ignorable字段，仓库中的生成规范 website/errors/CLAUDE.md 明确说明：大多数标识符为true；只有那些在规则构建链中调用->nonIgnorable()、或标识符以phpstan./phpstanPlayground.开头的才会是false。因此class.nameCase属于可通过配置放行的可忽略错误，这一特性在文末"如何忽略"一节展开。

触发示例：什么代码会报 class.nameCase

原文档给出了最小可复现示例。类声明为MyClass，但实例化时写成了全小写的myclass：

<?php declare(strict_types = 1); class MyClass { } $obj = new myclass(); // reported: Class MyClass referenced with incorrect case: myclass.

PHPStan 会在第 8 行给出类似如下的报告：

Class MyClass referenced with incorrect case: myclass.

注意报告信息会同时给出声明时的正确类名（MyClass）与被引用的错误形式（myclass），方便你直接定位差异。这是class.nameCase家族错误区别于其他"类不存在"类错误的关键特征——类确实存在，只是大小写对不上。

为什么会报告：PHP 大小写语义与工程实践的冲突

原文档对这一点的解释可以概括为三条，这也是 PHP 语言层面的客观事实：

1. PHP 类名在运行时大小写不敏感。new myclass()与new MyClass()在运行时指向同一个类，代码可以正常执行，不会报致命错误；
2. 大小写不一致损害可读性、容易造成困惑。读者看到myclass无法立刻与声明的MyClass建立对应关系，在大型代码库中这种歧义会被放大；
3. 在大小写敏感的文件系统上可能引发自动加载失败。Linux、macOS（默认大小写敏感）等系统上，遵循 PSR-4 的自动加载器按MyClass推导文件路径MyClass.php，而myclass会推导出myclass.php，两个路径在大小写敏感的文件系统上是不同的文件，导致类无法被加载。PHPStan 报告此错误正是为了推动代码库中一致、正确的大小写习惯，把隐患消灭在运行之前。

值得注意的是，PHPStan 对类名大小写的检查覆盖了类名出现的几乎所有语法位置。根据 website/src/errorsIdentifiers.json 中class.nameCase与规则的映射，同一个标识符由PHPStan\Rules\ClassCaseSensitivityCheck统一产生，并通过以下规则在各类使用场景中被触发：

也就是说，一旦类名被以错误大小写引用——无论是实例化、instanceof、继承、实现接口、使用 trait、访问类常量、使用属性还是类型别名——都会统一归类到class.nameCase之下。这是理解该标识符适用范围的关键：它不是一个单点检查，而是贯穿类名所有使用位置的统一校验。

如何修复：与声明保持完全一致的大小写

修复方式非常直接：使用与类定义完全一致的大小写。原文档给出的 diff：

-$obj = new myclass(); +$obj = new MyClass();

同理，其他使用位置也应统一修正。例如instanceof与类型声明：

-if ($x instanceof myclass) { +if ($x instanceof MyClass) { -function doFoo(myclass $c): void +function doFoo(MyClass $c): void

修复后 PHPStan 对该位置的报告即消失。整个家族的错误遵循同一原则，参见同族文档 enum.nameCase.md（枚举名）、interface.nameCase.md（接口名）、trait.nameCase.md（trait 名）。

底层实现：ClassCaseSensitivityCheck 统一校验器

从 website/src/errorsIdentifiers.json 的映射可以确认，class.nameCase的全部相关规则最终都指向同一个底层校验类：PHPStan\Rules\ClassCaseSensitivityCheck（在phpstan/phpstan-src仓库的src/Rules/ClassCaseSensitivityCheck.php中，报告逻辑位于该文件的第 63 行附近）。

从源码结构可以推断其工作方式：

1. 每个使用类名的规则先解析出被引用名称与声明名称：例如InstantiationRule在遇到new myclass()时，将引用名myclass解析到实际的类反射对象MyClass；
2. 交由ClassCaseSensitivityCheck统一比较大小写：将引用名与声明名做大小写敏感的比较，不一致则生成错误消息Class MyClass referenced with incorrect case: myclass.；
3. 共享同一个标识符：所有规则复用同一校验器、同一错误消息格式，因此无论错误出现在哪个语法位置，标识符始终是class.nameCase，便于统一配置忽略或基线管理。

这种"单一校验器 + 多规则复用"的设计也解释了为何该标识符覆盖的场景如此之广——校验逻辑只写一次，其余规则只需把自己的使用场景接进来即可。

相关配置：内置类与函数名大小写检查

虽然class.nameCase本身是默认启用的核心检查（对用户自定义类始终生效），但 PHPStan 还提供了两个相邻的、默认关闭的大小写检查配置，需要在 website/src/config-reference.md 中了解清楚以免混淆：

checkInternalClassCaseSensitivity

• 默认值：false（strict-rules 会将其设为true）
• 作用：当设置为true时，报告内置类（PHP 自带类，如\stdclass引用\stdClass）的大小写错误。从该配置的默认值可以推断：PHPStan 默认只检查用户自定义类的类名大小写，内置类默认不检查，因为内置类名的大小写问题在实践中影响更小。

checkFunctionNameCase

• 默认值：false（strict-rules 会将其设为true）
• 作用：当设置为true时，报告函数和方法调用的名称大小写错误。这正是同族标识符 function.nameCase.md、method.nameCase.md、staticMethod.nameCase.md 的前置开关——这三个标识符仅在checkFunctionNameCase开启时才会报告。

parameters: checkFunctionNameCase: true checkInternalClassCaseSensitivity: true

需要强调：这两个配置项都不影响class.nameCase对自定义类名的默认检查。class.nameCase是核心规则的一部分，默认开启；配置只是用来扩展检查范围（函数/方法名、内置类名）。

如何忽略：ignorable 与基线

由于 frontmatter 中ignorable: true，class.nameCase可以像其他可忽略错误一样，通过ignoreErrors规则或基线文件放行。例如在phpstan.neon中：

ignoreErrors: - identifier: class.nameCase path: src/legacy/*.php

或者直接引用错误消息文本。在大型存量代码库中，更常见的是先生成基线再逐步清零。仓库的 e2e 集成测试提供了大量基线引用nameCase标识符的真实范例，例如 e2e/integration/doctrine-dbal-baseline.neon、e2e/integration/typo3-baseline.neon、e2e/integration/efabrica-phpstan-latte-baseline.neon，可以作为在第三方生态代码中忽略该类报告的实际参考。

同族错误标识符一览

class.nameCase属于 PHPStan 大小写一致性检查（name case）错误家族。仓库website/errors/目录下与之配套的文档还包括：

它们共享同一个设计理念：PHP 语言运行时对符号名大小写不敏感，但工程规范要求严格一致。其中类、接口、trait、枚举的大小写检查默认开启（其中内置类需checkInternalClassCaseSensitivity），而函数/方法调用的大小写检查则属于可选的严格性增强，默认关闭。

小结

• class.nameCase报告"以错误大小写引用类名"，报告消息同时给出正确名称与错误形式；
• 根因是 PHP 类名运行时大小写不敏感，但错误大小写损害可读性并可能在大小写敏感文件系统上破坏自动加载；
• 修复方式即统一为声明时的确切大小写；
• 底层由ClassCaseSensitivityCheck统一实现，通过InstantiationRule、ExistingClassInInstanceOfRule、ClassConstantRule等十余条规则覆盖类名的全部使用位置；
• 该标识符ignorable: true，可配置忽略或纳入基线管理；
• 相邻配置checkFunctionNameCase与checkInternalClassCaseSensitivity默认关闭，用于扩展函数/方法名与内置类名的大小写检查。

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