Psalm 的 PossiblyFalseIterator 错误详解:当 foreach 遍历的变量可能为 false 时
Psalm 的 PossiblyFalseIterator 错误详解:当 foreach 遍历的变量可能为 false 时
导读
PossiblyFalseIterator 是 Psalm(PHP 静态分析工具)在分析 foreach 循环时报告的一类“可能存在的运行时错误”:当被遍历的变量类型联合(union type)中包含 false 时,Psalm 无法保证该变量在运行时一定可迭代,于是抛出此错误。本文将围绕 PossiblyFalseIterator.md 展开:先解释错误的触发条件与源码判定逻辑,再给出多种修复方案(类型收窄、显式判断、docblock 标注、baseline 与抑制),并说明它与其他同类迭代器错误(PossiblyNullIterator、PossiblyInvalidIterator)的边界,帮助你在实际项目中正确消除这类告警。
什么是 PossiblyFalseIterator
官方定义
根据 PossiblyFalseIterator.md,该错误在“试图遍历一个可能为 false 的值”时被报告(Emitted when trying to iterate over a value that may be false)。也就是说,foreach 的遍历源变量的类型中包含 false 分支,而 false 本身不可迭代,因此代码在运行时可能触发 TypeError 或进入意外分支。
最小复现示例
原文档给出的示例:
<?php
$arr = rand(0, 1) ? [1, 2, 3] : false;
foreach ($arr as $a) {}
这里 rand(0, 1) 的结果不确定,Psalm 会把 $arr 推断为联合类型 array{0: 1, 1: 2, 2: 3}|false(即“数组 或 false”)。由于存在 false 分支,Psalm 判定遍历操作不安全,报告 PossiblyFalseIterator。
源码中的判定逻辑
错误类定义
PossiblyFalseIterator 在 src/Psalm/Issue/PossiblyFalseIterator.php 中定义,继承自 CodeIssue,并声明了两个关键常量:
ERROR_LEVEL = 3:该错误属于“第 3 级”错误;SHORTCODE = 164:Psalm 的错误短代码,可用于--report输出、baseline 与@psalm-suppress定位。
该错误类在 src/Psalm/Internal/PreloaderList.php 中被预加载注册,确保在分析过程中可被识别与报告。
触发位置与判定条件
实际判定发生在 src/Psalm/Internal/Analyzer/Statements/Block/ForeachAnalyzer.php 的 checkIteratorType() 方法中。ForeachAnalyzer::analyze() 会先取得 foreach 表达式($stmt->expr)的推断类型($iterator_type),然后调用 checkIteratorType() 依次检查各种“不可迭代”情形,相关核心代码如下:
if ($iterator_type->isNull()) {
// 报告 NullIterator
...
}
if ($iterator_type->isNullable() && !$iterator_type->ignore_nullable_issues) {
// 报告 PossiblyNullIterator
...
}
if ($iterator_type->isFalsable() && !$iterator_type->ignore_falsable_issues) {
IssueBuffer::maybeAdd(
new PossiblyFalseIterator(
'Cannot iterate over falsable var ' . $iterator_type,
new CodeLocation($statements_analyzer->getSource(), $expr),
),
$statements_analyzer->getSuppressedIssues(),
);
return null;
}
几个值得注意的实现细节:
- 判定依据是
isFalsable():只要联合类型中存在false原子类型(TFalse),就认为“可能为 false”,进而触发该错误;ignore_falsable_issues为 false 时才会报告(即未被显式忽略)。 - 错误信息模板:报告的消息为
Cannot iterate over falsable var {类型},例如Cannot iterate over falsable var array{0: 1, 1: 2, 2: 3}|false。 - 遍历中断语义:
checkIteratorType()返回null(而非false)表示“可能有问题但继续分析”,只有返回false才真正中断对该foreach的分析(如纯null的情况)。这意味着 Psalm 在报告PossiblyFalseIterator后,仍会继续对循环体做类型分析,尽量给出更多诊断信息。 - 后续原子类型校验:检查完 falsable 之后,该方法会继续遍历
$iterator_type->getAtomicTypes(),对TArray、TKeyedArray、TNull、TFalse等分别处理;其中TFalse原子类型会使always_non_empty_array变为 false,用于循环体内对数组非空性的精细化推断。
此外,ForeachAnalyzer::analyze() 在 checkIteratorType() 通过后,会使用 AssertionReconciler::reconcile(new Assertion\NonEmpty(), ...) 对循环内作用域的遍历变量做“非空”收窄,这也是理解“为什么循环体内类型会变”的关键。
错误级别与抑制方式
错误级别:默认按“错误”上报,第 4 级起降级为 info
根据 error_levels.md 的级别表:
| 级别 | 严格程度 | 相对上一级的变化 |
|---|---|---|
| 1(最严格) | 所有问题均为错误 | 新增 Mixed* 系列、LessSpecificReturnType 为错误 |
| 2(默认) | 大多数问题 | Mixed* 降级为 info |
| 3 | 中等 | Deprecated*、MissingParamType、PropertyNotSetInConstructor 降级为 info |
| 4 | 宽松 | Possibly* 系列问题降级为 info |
| 5 | 更宽松 | InvalidScalarArgument、RedundantCondition、TooManyArguments 降级为 info |
PossiblyFalseIterator 属于 Possibly* 系列,在 error_levels.md 的“按级别分组”列表中与 PossiblyFalseArgument、PossiblyFalseOperand、PossiblyFalseReference 等并列出现。因此在默认 level 2(以及更严格的 level 1)下,它会被当作阻塞性错误上报;当把 errorLevel 调高到 4 及以上时,它会被降级为 info(非阻塞提示),但仍会出现在报告中。
可通过在 psalm.xml 中设置 errorLevel 调整全局严格程度:
<psalm errorLevel="4">
<projectFiles>
<directory name="src" />
</projectFiles>
</psalm>
用 @psalm-suppress 局部抑制
如果某处代码确实无法避免遍历可能为 false 的变量(例如第三方数据的特殊形态),可以在语句或函数 docblock 上添加抑制注释(参考 dealing_with_code_issues.md 中的 docblock suppression 一节):
<?php
$arr = rand(0, 1) ? [1, 2, 3] : false;
/** @psalm-suppress PossiblyFalseIterator */
foreach ($arr as $a) {}
若要一次性抑制该作用域内的全部问题,可写成 @psalm-suppress all。
用 baseline 记录存量问题
对于存量代码中大量暂时无法修复的同类告警,可以使用 baseline 机制“存档”而非直接抑制(详见 dealing_with_code_issues.md 的 “Using a baseline file” 一节):
./vendor/bin/psalm --set-baseline=psalm-baseline.xml
baseline 会让 Psalm 在后续运行中不再重复报告这些已记录的问题,同时新代码中新增的同类问题仍会被正常发现,是一种比全局降级更可控的过渡方案。
修复实战:如何消除 PossiblyFalseIterator
方案一:先判空/判 false,再遍历(推荐)
通过 is_array() 或与 false 的显式比较收窄类型,把不可迭代分支排除在 foreach 之前:
<?php
$arr = rand(0, 1) ? [1, 2, 3] : false;
if (!is_array($arr)) {
return; // 或 throw、continue 等
}
foreach ($arr as $a) {}
is_array() 收窄后,Psalm 能确认 $arr 在此处一定为数组类型,错误自然消失。
方案二:三元表达式直接兜底为空数组
如果不希望引入早退分支,可以直接把 false 分支替换为可迭代的空数组:
<?php
$arr = rand(0, 1) ? [1, 2, 3] : [];
foreach ($arr as $a) {}
这样联合类型变为 array{0: 1, 1: 2, 2: 3}|array{},所有分支都可安全遍历(空数组遍历本身就是安全的),不会触发 PossiblyFalseIterator。
方案三:使用 @var 或 docblock 标注显式类型
当变量来自无法静态推断的调用(如魔术方法、第三方库返回 mixed 包装)时,可以显式声明类型:
<?php
/** @var array<int, int>|false $arr */
$arr = getPossiblyFalseArray();
foreach ($arr as $a) {}
注意:这仍会报告 PossiblyFalseIterator,因为它并未移除 false 分支——只有配合 is_array() 判断或 @psalm-assert 断言才能真正收窄。
方案四:让调用方直接返回“数组或 null”
如果 false 是函数返回的“失败”信号,更好的做法是改用可空返回类型,把判断逻辑交给 PossiblyNullIterator 与 null 检查体系(见下文对比),例如:
<?php
/** @return array<int, int>|null */
function getArray(): ?array { ... }
$arr = getArray();
if ($arr === null) {
return;
}
foreach ($arr as $a) {}
与其他迭代器错误的边界
Psalm 的 ForeachAnalyzer::checkIteratorType() 对不可迭代类型做了分级处理,PossiblyFalseIterator 只是其中之一。容易混淆的三兄弟对比如下:
| 错误 | 触发条件 | 典型示例 |
|---|---|---|
PossiblyFalseIterator |
遍历变量可能为 false(isFalsable()) |
$arr = rand(0, 1) ? [1, 2, 3] : false; |
| PossiblyNullIterator | 遍历变量可能为 null(isNullable()) |
function foo(?array $arr) : void { foreach ($arr as $a) {} } |
| PossiblyInvalidIterator | 遍历变量的类型存在完全不可迭代的分支(如 string) |
$arr = rand(0, 1) ? [1, 2, 3] : "hello"; |
三者在源码中的判定顺序依次为:纯 null(NullIterator,确定性问题,直接中断分析)→ 可空(PossiblyNullIterator)→ 可 false(PossiblyFalseIterator)→ 逐原子类型校验(PossiblyInvalidIterator、InvalidIterator、RawObjectIteration 等)。理解这一顺序有助于你判断:当一个变量同时“可能为 null 且可能为 false”时,Psalm 会优先报告哪一个,以及修复后下一层错误是否会暴露出来。
快速验证:在项目中复现与消除
在本地项目中可用 command_line_usage.md 介绍的方式运行 Psalm 快速验证:
# 在项目根目录运行(需先完成配置,参照 docs/running_psalm/configuration.md)
./vendor/bin/psalm
# 只检查单个文件
./vendor/bin/psalm path/to/file.php
# 以 JSON 报告输出,便于配合 psalm-review 逐条审阅
./vendor/bin/psalm --report=report.json
将文中的复现代码保存为 test.php 后运行 ./vendor/bin/psalm test.php,应能看到类似 PossiblyFalseIterator: Cannot iterate over falsable var array{0: 1, 1: 2, 2: 3}|false 的输出(短代码 164);按上述修复方案改写后再运行,告警即消失。Psalm 的退出码约定为:0 表示运行成功且无问题,2 表示成功完成但发现了一些问题(详见 command_line_usage.md 的 Exit status 一节),因此 CI 中可直接据此判断是否失败。
小结
PossiblyFalseIterator在 Psalm 中对应短代码164、错误级别 3,由 ForeachAnalyzer.php 的checkIteratorType()在检测到遍历变量isFalsable()时报告。- 它表示代码在运行时可能对
false执行foreach,属于“可能存在运行时错误”,而非纯逻辑上的死代码。 - 最干净的修复是用
is_array()收窄 + 早退,或把 false 分支替换为空数组;必要时使用@psalm-suppress或 baseline 过渡。 - 当
errorLevel >= 4时该错误会降级为 info;若想保持严格检查,建议保持在默认 level 2 并及时修复。