Psalm 的 PossiblyFalseIterator 错误详解:当 foreach 遍历的变量可能为 false 时

原创2026-10-12 21:49:191,677 阅读
文章标签:开发工具代码质量质量保障

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;
}

几个值得注意的实现细节:

  1. 判定依据是 isFalsable():只要联合类型中存在 false 原子类型(TFalse),就认为“可能为 false”,进而触发该错误;ignore_falsable_issues 为 false 时才会报告(即未被显式忽略)。
  2. 错误信息模板:报告的消息为 Cannot iterate over falsable var {类型},例如 Cannot iterate over falsable var array{0: 1, 1: 2, 2: 3}|false。
  3. 遍历中断语义:checkIteratorType() 返回 null(而非 false)表示“可能有问题但继续分析”,只有返回 false 才真正中断对该 foreach 的分析(如纯 null 的情况)。这意味着 Psalm 在报告 PossiblyFalseIterator 后,仍会继续对循环体做类型分析,尽量给出更多诊断信息。
  4. 后续原子类型校验:检查完 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 并及时修复。
登录后查看全文
psalm