PHPStan 错误标识符 `impure.superglobal` 全解析：纯函数访问超全局变量的检测与修复

PHPStan 错误标识符impure.superglobal全解析：纯函数访问超全局变量的检测与修复

【免费下载链接】phpstanPHP Static Analysis Tool - discover bugs in your code without running it!项目地址: https://gitcode.com/gh_mirrors/ph/phpstan

本篇文章围绕 PHPStan 的错误标识符impure.superglobal展开，说明当一个被标记为@phpstan-pure的函数访问 PHP 超全局变量（$_GET、$_POST、$_SERVER等）时，静态分析器为什么会将其判定为"不纯"，并提供两种可落地的修复方案。读完本文，你将理解 PHPStan 纯函数（pure function）分析的判定边界、超全局变量被视为外部可变状态的原因，以及如何在保持函数纯度与访问请求数据之间做出正确取舍。

一、错误标识符概览

impure.superglobal是 PHPStan 在 website/src/errorsIdentifiers.json 中注册的标准错误标识符之一，其官方定义为：

Pure function accesses a superglobal variable.（纯函数访问了超全局变量。）

在 website/errors/impure.superglobal.md 的文档 frontmatter 中，该标识符被标记为ignorable: true，意味着开发者可以在phpstan.neon的ignoreErrors中按标识符精确忽略此错误（具体忽略语法参见 网站错误处理文档 所描述的标识符体系）。

从标识符前缀体系来看，impure.*一族属于 PHPStan"纯度分析"（purity analysis）的一部分。errorsIdentifiers.json中与它同族的标识符还包括impure.echo、impure.print、impure.functionCall、impure.methodCall、impure.global、impure.static、impure.new等，它们共同约束"标记为纯的函数体内不得出现副作用"。

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

以下是最小复现示例（来自官方文档）：

<?php declare(strict_types = 1); /** @phpstan-pure */ function getParam(string $key): ?string { return $_GET[$key] ?? null; }

在这个例子中，函数getParam通过@phpstan-pure注解声明自己是"纯函数"，但函数体内部直接读取了超全局变量$_GET。PHPStan 在分析时发现这种矛盾，便会报告impure.superglobal。

三、为什么会报告该错误？

1. 纯函数的定义

纯函数（pure function）有两个核心特征：

• 确定性：相同输入必然产生相同输出；
• 无副作用：不修改外部状态，也不依赖外部可变状态。

正因如此，PHPStan 要求被标记为@phpstan-pure的函数"只能依赖其输入参数"（Pure functions should only depend on their input parameters）。

2. 超全局变量属于外部可变状态

PHP 的超全局变量共有 9 个，全部由运行时（Web 服务器或 CLI 环境）在脚本执行前注入，属于典型的全局可变状态：

这些变量在两次函数调用之间可能被外部环境改变，甚至在同一请求内也会随程序执行而变化。因此，读取超全局变量等同于读取外部可变状态，破坏了纯函数"相同输入必得相同输出"的承诺——即使函数参数完全相同，两次调用的返回值也可能不同。

3. 为什么是 definitely impure 而不是 possibly impure？

PHPStan 的标识符体系中还存在一个近亲possiblyImpure.superglobal（见 website/errors/possiblyImpure.superglobal.md）。但该文档明确指出：这个标识符在实践中不会被报告，因为超全局访问总是被判定为"确定不纯"（definitely impure），而非"可能不纯"，因此 PHPStan 统一报告impure.superglobal。换句话说，possiblyImpure.superglobal只是一个预留标识符，真正的检测结果都落在impure.superglobal上。

从源码结构看（对应 website/src/errorsIdentifiers.json 中impure.superglobal与possiblyImpure.superglobal两个条目的并存），这体现了 PHPStan 纯度分析的一个设计决策：对超全局变量的访问不存在"或许可接受"的中间地带，只要纯函数碰了超全局，就一律按不纯处理。

四、如何修复该错误

官方文档提供了两种修复路径，按推荐优先级排列如下。

方案一：把需要的值作为参数传入（推荐）

将函数改为"从外部接收数据"，让函数体不再触碰超全局变量：

<?php declare(strict_types = 1); -/** @phpstan-pure */ -function getParam(string $key): ?string +/** @phpstan-pure */ +function getParam(array $params, string $key): ?string { - return $_GET[$key] ?? null; + return $params[$key] ?? null; }

调用侧在函数外读取超全局并传入：

$value = getParam($_GET, 'key');

这样函数保持纯性，且更易于单元测试——测试时直接传入构造好的$params数组即可，无需模拟 HTTP 环境。possiblyImpure.superglobal文档中的修复示例（将$_SERVER['HTTP_USER_AGENT']改为参数$userAgent传入）也是同一思路。

方案二：移除@phpstan-pure注解

如果该函数的功能本质就是读取请求数据（例如一个getUserAgent(): string的辅助函数），那么它天然依赖全局状态，此时应该诚实声明：

<?php declare(strict_types = 1); function getParam(string $key): ?string { return $_GET[$key] ?? null; }

去掉@phpstan-pure后，PHPStan 不再以纯函数标准约束它，impure.superglobal也随之消失。这与 PHPStan 对"副作用代码"的宽容策略一致：只有显式声明纯性时，才会对副作用严格把关。

关于忽略错误

由于impure.superglobal是ignorable: true的标识符，理论上也可以使用ignoreErrors配置按标识符忽略。但官方文档并未推荐这种方式——相比让分析器"闭嘴"，通过参数化重构保持函数纯度，或者移除纯函数注解诚实表达意图，才是更符合静态分析初衷的做法。

五、与其他impure.*标识符的关联

impure.superglobal并不是孤立存在的。在 website/src/errorsIdentifiers.json 中，impure.*一族还包括：

• impure.echo/impure.print：纯函数中使用echo/print产生输出；
• impure.exit/impure.die：纯函数中终止执行；
• impure.functionCall/impure.methodCall：纯函数调用其他不纯的函数/方法；
• impure.new：纯函数中实例化对象；
• impure.global/impure.staticPropertyAccess：纯函数中读写全局变量或静态属性；
• impure.include/impure.require：纯函数中引入文件。

这些标识符共同构成了 PHPStan 对"纯函数体内副作用"的完整检测网络。impure.superglobal是其中针对超全局变量这一特定副作用来源的专门检测，与其他标识符互为补充：一个纯函数可能因为访问$_GET报告impure.superglobal，也可能因为调用var_dump()报告impure.functionCall，两者并不互斥。

六、总结

• impure.superglobal在被标记为@phpstan-pure的函数访问 9 个 PHP 超全局变量中的任何一个时触发；
• 触发根因是超全局变量属于外部可变状态，读取它会破坏纯函数"相同输入必得相同输出"的确定性承诺；
• 该错误为"确定不纯"，不会降级为possiblyImpure.superglobal；
• 推荐修复方式是通过参数把值传入函数，保持函数纯性；若函数职责就是读取请求数据，则移除@phpstan-pure注解。

理解并正确使用纯函数注解，是让 PHPStan 纯度分析真正发挥作用的前提。当你的代码库中大量函数被标记为纯函数时，impure.superglobal这类标识符能帮助你在早期发现"看似纯、实则依赖全局状态"的隐患，从而写出更可测试、更可预测的代码。

【免费下载链接】phpstanPHP Static Analysis Tool - discover bugs in your code without running it!项目地址: https://gitcode.com/gh_mirrors/ph/phpstan