企业官网建设流程全解析

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

本文围绕 PHPStan 错误标识impureMethod.pure展开，讲解其触发条件、判定逻辑（仅针对 final 类或 final 方法）以及两种修复路径：改为@phpstan-pure或直接移除标注。读完本文，你将掌握纯度（purity）标注与 PHPStan 自动推断的关系，并能结合源码映射、相关错误标识（如impureFunction.pure、method.impure）和配套标签（@phpstan-all-methods-pure等）在日常项目中准确管理方法纯度契约。

错误标识与文档来源

impureMethod.pure是 PHPStan 众多可忽略错误标识（error identifier）之一，其官方解释文档位于 website/errors/impureMethod.pure.md。文档 frontmatter 中记录了三个关键元数据字段：

在 website/src/errorsIdentifiers.json 的标识符注册表中，impureMethod.pure被映射到PHPStan\Rules\Pure\PureMethodRule规则类，并由纯度分析的核心检查器FunctionPurityCheck完成实际检测，同系列标识符还涵盖函数（PureFunctionRule）与属性钩子（PurePropertyHookRule）场景，说明该错误由统一的纯度分析基础设施产出，只是针对不同代码单元（方法、函数、属性钩子）暴露了不同的标识符。

Code example：触发该错误的代码形态

根据 website/errors/impureMethod.pure.md 的官方示例，一个最简触发用例为：

<?php declare(strict_types = 1); final class Calculator { /** @phpstan-impure */ public function add(int $a, int $b): int { return $a + $b; } }

这段代码的关键特征：

• 方法add()被@phpstan-impure标注为"有副作用"；
• 但方法体只是纯算术计算return $a + $b;，不执行任何 I/O、不修改外部状态、不调用其他不纯代码；
• 类Calculator被声明为final，因此方法不可被子类覆盖。

Why is it reported：为什么 PHPStan 会报告

PHPStan 在分析一个被标记为@phpstan-impure的方法时，会在其方法体内查找实际存在的副作用点（impure points），包括但不限于：

• I/O 操作（如echo、print、文件读写）；
• 对外部状态或全局状态的修改（如属性赋值、静态属性访问）；
• 对其他不纯（impure）函数或方法的调用。

当方法体被判定为完全无副作用时，@phpstan-impure标注与实际行为不符，PHPStan 便会报告impureMethod.pure。标注一个无副作用的方法为 impure 具有误导性：调用方无法从纯度优化中受益，且标注与真实行为不一致，破坏了纯度契约的可信度。

需要特别注意的是该错误仅针对不可被覆盖（cannot be overridden）的方法，具体有两种情形：

1. 方法所在的类被声明为final；
2. 方法自身被声明为final。

对于非 final 方法，由于子类有可能引入副作用（例如子类覆盖后在方法内写文件、改全局状态），PHPStan 无法确认该方法在所有实现下都无副作用，因此不会报告impureMethod.pure。这正是final关键字在纯度分析中的关键作用——它让分析器可以基于当前类的确定性行为做出结论。

这一设计逻辑与 method.impure 形成对照：当父类或接口将方法声明为@phpstan-pure时，所有覆盖该方法（override）的实现也必须是纯的；反之，final保证了方法不会被覆盖，从而允许 PHPStan 以当前实现为准判断其纯度。

How to fix it：两种修复路径

修复方式一：改为 @phpstan-pure

如果方法确实没有任何副作用，将其标注改为@phpstan-pure，明确告知 PHPStan 该方法是纯函数：

-/** @phpstan-impure */ +/** @phpstan-pure */ public function add(int $a, int $b): int { return $a + $b; }

修复方式二：直接移除标注，让 PHPStan 自动推断

也可以完全移除@phpstan-impure标注，由 PHPStan 基于方法体内容自动推断纯度。PHPStan 默认将所有返回值的方法视为纯的（见 website/src/writing-php-code/phpdocs-basics.md 中 "Impure functions" 一节），因此对于纯计算类方法，无标注时 PHPStan 会正确地将其推断为纯方法：

-/** @phpstan-impure */ public function add(int $a, int $b): int { return $a + $b; }

移除标注后，方法默认按纯函数处理，第二处同一作用域内的调用将返回相同的收窄类型，这对类型推断与代码优化都更有利。

源码级佐证：纯度分析的实现基础设施

虽然impureMethod.pure的规则类为PureMethodRule，其底层检查逻辑集中在FunctionPurityCheck中，这一点可从 website/src/errorsIdentifiers.json 的标识符映射中看出——impureMethod.pure、impureFunction.pure、impurePropertyHook.pure三个标识符均指向同一检查器（FunctionPurityCheck）。从该映射结构可以推断：

• PHPStan 将"判断一段代码是否包含副作用点"的能力抽取为共享的纯度检查器；
• 方法（PureMethodRule）、函数（PureFunctionRule）、属性钩子（PurePropertyHookRule）各自持有独立的规则类，负责报告时机与错误标识差异，但共享同一套副作用检测逻辑；
• 因此在同一次分析运行中，方法、函数与属性钩子的纯度判定标准是一致的，这保证了错误标识之间的行为可预期。

扩展阅读：与纯度标注相关的完整标签体系

理解impureMethod.pure需要掌握 PHPStan 的纯度（purity）标注体系，详见 website/src/writing-php-code/phpdocs-basics.md：

@phpstan-impure 的适用场景

PHPStan 默认将所有返回值的方法视为纯的——这意味着在同一作用域内对同一函数的第二次调用会返回相同的收窄类型。如果你的函数可能基于随机数生成器、数据库或时间等全局状态，在连续调用中返回不同值，则该函数是不纯的，需要用@phpstan-impure告知 PHPStan：

/** @phpstan-impure */ function impureFunction(): bool { return rand(0, 1) === 0 ? true : false; }

这里的rand()就是典型的不纯调用——它不满足impureMethod.pure的触发前提，因此不会误报。

@phpstan-pure 与 rememberPossiblyImpureFunctionValues

@phpstan-pure标签用于在必要时显式声明纯度，例如当你在配置文件中设置了rememberPossiblyImpureFunctionValues: false时，可以通过该标签恢复对特定函数的纯度声明（配置项见 website/src/config-reference.md）。这也是impureMethod.pure修复方案一把标注改为@phpstan-pure的语义基础。

类级别批量标注：@phpstan-all-methods-pure / @phpstan-all-methods-impure

（该能力自 PHPStan 2.1.39 起可用）对于所有方法均不纯（或均纯）的类，可以在类级别使用@phpstan-all-methods-impure（或@phpstan-all-methods-pure），单个方法仍可通过@phpstan-pure/@phpstan-impure覆盖类级别设置：

/** @phpstan-all-methods-impure */ class UserRepository { public function findById(int $id): ?User { ... } public function findAll(): array { ... } public function count(): array { ... } /** @phpstan-pure */ public function buildCacheKey(int $id): string { ... } }

这类类级别标注同样遵循"标注需与实现一致"的原则——如果一个类被标注为@phpstan-all-methods-pure，但某个方法实际包含副作用，PHPStan 同样会报告对应的纯度错误。

条件纯度：@pure-unless-callable-is-impure

（该能力自 PHPStan 2.2 起可用）接受 callable 的高阶函数只有在收到的回调本身是纯的时才可能是纯的，类似于 PHP 原生array_map()的行为。此时可用@pure-unless-callable-is-impure标注函数或方法在指定参数的回调不纯时才不纯：

/** * @param callable(int): int $f * @param array<int> $arr * @return array<int> * @pure-unless-callable-is-impure $f */ function myMap(callable $f, array $arr): array { // ... }

同系列错误标识对照

impureMethod.pure属于"标注与实际纯度不符"家族，理解相邻标识有助于快速定位问题：

其中impure.*系列（如impure.echo、impure.methodCall、impure.propertyAssign）通常与method.impure/ 纯方法中的副作用检测配套出现，而impureMethod.pure则专指标注与实际行为"反向不匹配"的情形——标注了不纯，实际却很纯。

最佳实践小结

1. 优先依赖自动推断：纯计算方法不要加任何纯度标注，让 PHPStan 默认的"返回值方法视为纯"机制生效，避免标注与实际实现漂移；
2. 仅在真正不纯时使用 @phpstan-impure：方法体内存在 I/O、全局状态修改或不纯调用时才需要该标签，例如依赖随机数、数据库或时间的工厂方法；
3. final 是关键前提：impureMethod.pure只在 final 类或 final 方法上报告，若需 PHPStan 对该方法做纯度判定，请确保其不可被覆盖；反之，若方法可能被子类重写并引入副作用，则不要标注纯，PHPStan 也不会误报；
4. 善用类级别标注：对整个类的方法统一声明纯度时使用@phpstan-all-methods-pure/@phpstan-all-methods-impure，并为个别方法做单点覆盖；
5. 配合 ignoreErrors 精确管理：由于ignorable为true，在确有合理业务原因时可通过ignoreErrors配合错误标识impureMethod.pure做定点豁免，但应优先修复标注本身。

延伸学习资源

• 纯度标签的完整说明与配置项rememberPossiblyImpureFunctionValues：website/src/writing-php-code/phpdocs-basics.md
• 错误标识到规则类、源码位置的映射（含PureMethodRule/PureFunctionRule/PurePropertyHookRule）：website/src/errorsIdentifiers.json
• 同族错误impureFunction.pure（函数版）：website/errors/impureFunction.pure.md
• 反向约束错误method.impure（覆盖纯方法时）：website/errors/method.impure.md
• 全部纯度相关错误标识文档：website/errors 目录

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