PHPStan 错误标识符 equal.alwaysFalse 全解析：== 松散比较为何永远为 false

equal.alwaysFalse 是 PHPStan 在类型分析层面报告的一类"恒假比较"错误标识符：当使用松散比较运算符 == 的表达式基于操作数的静态类型可以确定永远求值为 false 时触发。本文以 equal.alwaysFalse.md 为主体，结合本仓库中标识符的规则映射与文档生成机制，讲解该错误的触发条件、PHP 类型转换（type juggling）背后的原理，以及三种可落地的修复方案，帮助你识别死代码与逻辑错误。

错误标识符速览

属性	值
标识符	equal.alwaysFalse
对应规则类	PHPStan\Rules\Comparison\ConstantLooseComparisonRule（见 errorsIdentifiers.json）
触发时机	松散比较 == 的操作数类型决定比较结果恒为 false
可否忽略	可忽略（ignorable: true），支持通过 ignoreErrors / baseline 屏蔽

该标识符文档遵循仓库统一的错误文档结构（frontmatter + Code example + Why is it reported? + How to fix it），见 website/errors/CLAUDE.md 中的格式说明。文档与 website/src/errorsIdentifiers.json 中的规则映射一一对应，后续讲解将以此为事实依据。

触发示例：positive-int 与 0 的恒假比较

原文档给出的最小触发示例：

<?php declare(strict_types = 1);

/** @param positive-int $i */
function doFoo(int $i): void
{
	if ($i == 0) {
		// never reached
	}
}

关键点在于 PHPDoc 类型标注 @param positive-int $i。positive-int 是 PHPStan 的内置整数区间类型，表示"大于等于 1 的整数"（即 int<1, max> 的语义别名）。因此：

• $i 的静态类型区间为 [1, +∞)；
• 与字面量 0 做松散比较时，无论 $i 在运行时取何值，$i == 0 都不可能成立；
• PHPStan 在静态分析阶段即可判定该分支永远不会进入，于是标记 equal.alwaysFalse。

需要注意的是，该规则基于操作数的静态类型进行判定，而非运行时值。只要两个操作数的类型交集为空——即使 PHP 的松散比较存在类型转换规则——比较结果就恒为 false。

为什么会被报告：松散比较与类型转换的交集分析

原文档的解释要点：松散比较 == 在 PHP 中会先执行类型转换（type juggling），再比较数值。例如 "0" == 0 为 true、null == 0 为 true（PHP 8 中部分边界语义有调整），这是很多隐性 bug 的来源。

但类型转换并不会让任意两个值相等。当 PHPStan 分析出两个操作数的类型域完全不相交时，即使考虑 PHP 的全部松散转换规则，二者也不可能相等。此时 == 表达式恒为 false，而代码中写出恒假的条件分支通常意味着：

1. 死代码——分支体永远不会执行，属于重构遗留或误写；
2. 逻辑错误——开发者本意是比较一个可达的值，却写成了不可能相等的值。

在示例中，$i 恒 >= 1，所以它与 0 的松散相等在类型层面被彻底排除。booleanAnd.alwaysFalse、identical.alwaysFalse、greater.alwaysFalse 等同类标识符（见 errorsIdentifiers.json 中相邻条目）遵循相似的分析路径，区别仅在于所用运算符（&&、===、> 等）。

从实现层面看，本仓库的 errorsIdentifiers.json 将 equal.alwaysFalse 映射到 PHPStan\Rules\Comparison\ConstantLooseComparisonRule，该规则类即负责收集"松散比较结果恒为常量"的场景并生成对应错误；website/errors/ 目录下的每个 .md 文件正是针对这类规则产出的标识符说明文档。仓库内还有独立的 identifier-extractor 工具，用于从规则源码中提取错误标识符，二者共同构成了标识符从"规则产生"到"文档化"的完整链路。

如何修复：三种可落地的方案

原文档给出了两种直接修复，这里补充为三种完整路径：

方案一：修正比较的目标值（推荐，先修逻辑 bug）

如果分支应当被执行，说明比较的值写错了，应改为实际可达到的值：

 /** @param positive-int $i */
 function doFoo(int $i): void
 {
-	if ($i == 0) {
+	if ($i == 1) {
 		// ...
 	}
 }

方案二：改用严格比较 ===

如果意图是"比较相同类型"，且操作数类型已由静态分析保证，可以用严格比较消除语义歧义：

 /** @param positive-int $i */
 function doFoo(int $i): void
 {
-	if ($i == 0) {
+	if ($i === 1) {
 		// ...
 	}
 }

严格比较 === 不进行类型转换，且 identical.alwaysFalse 会有独立标识符来报告恒假场景，语义更清晰，也是消除隐式转换副作用的首选写法。

方案三：通过类型收窄或忽略机制处理

• 收窄类型：在函数体内用原生类型声明或进一步的条件判断收窄 $i 的类型，使比较具备可达性；
• 忽略该错误：equal.alwaysFalse 在 frontmatter 中标记为 ignorable: true，意味着可以通过 ignoreErrors 配置（按 message 或按 identifier 匹配）或 baseline 文件屏蔽，适用于"确实想保留但暂不修复"的场景。仓库的 e2e/baseline/ 目录即演示了 baseline 文件的典型用法（phpstan.neon 通过 includes: [phpstan-baseline.neon] 引入忽略清单）。

在项目中定位与排查该错误的建议

1. 确认触发根因：先核对参与比较的操作数类型声明（原生类型与 PHPDoc 类型），判断是类型标注过窄、比较目标写错，还是确实需要忽略；
2. 优先修复逻辑而非忽略：alwaysFalse 类错误绝大多数指向真实死代码或逻辑缺陷，直接忽略会掩盖问题；
3. 结合 baseline 渐进治理：存量代码库可先跑 phpstan baseline 生成 baseline 快照，再逐步修复并移除对应条目，避免一次性大规模改动。

小结

equal.alwaysFalse 是 PHPStan 静态分析中"恒假比较"族错误的一个具体成员，其核心价值在于：把"运行时才会暴露的死分支"提前到静态分析阶段发现。理解它需要把握三点——松散比较的类型转换语义、操作数静态类型域是否相交、以及 == 与 === 的语义差异。当你的代码被报告此错误时，优先怀疑比较值写错或类型标注过窄，再考虑用 === 或 ignoreErrors 处理。

相关阅读：equal.alwaysFalse 官方标识符文档、标识符文档格式规范、错误标识符与规则映射表、标识符提取工具。