Psalm 的 ContinueOutsideLoop 问题详解:为什么循环外 continue 会被静态检出及其源码实现
Psalm 的 ContinueOutsideLoop 问题详解:为什么循环外 continue 会被静态检出及其源码实现
Psalm 的 ContinueOutsideLoop 问题用于捕获“在循环之外写 continue”这类代码——这类代码在 PHP 5.6 及以上版本直接编译失败(Fatal error: 'continue' not legal in this context),Psalm 能在不执行代码的情况下提前把它报出来。阅读本文后,你将了解该问题的触发条件与边界(例如顶层 switch 中的 continue 为何不报)、Psalm 中 ContinueAnalyzer 与 SwitchCaseAnalyzer 两条独立的检出路径、以及支撑循环控制流分析的 LoopScope / break_types 作用域模型,并结合仓库中的源码与测试用例给出可验证的依据。
问题定义:什么是 ContinueOutsideLoop
官方问题文档 ContinueOutsideLoop 的定义非常明确:
Emitted when encountering a
continuestatement outside a loop context.
最小触发示例:
<?php
$a = 5;
continue;
“Why this is bad” 一节的解释也很直接:代码在 PHP 5.6 及以上版本无法编译。continue 的语义是“跳到最近一层循环的迭代末尾”,如果当前没有任何循环上下文,该语句在 PHP 中是非法的,会直接产生 ParseError / CompileError。Psalm 将此类错误归入最高严重级别:
在问题类定义 src/Psalm/Issue/ContinueOutsideLoop.php 中可以看到:
final class ContinueOutsideLoop extends CodeIssue
{
public const ERROR_LEVEL = 7;
public const SHORTCODE = 43;
}
ERROR_LEVEL = 7:Psalm 错误等级体系中的最高级别(7),意味着任何 errorLevel 配置下都会被报告,通常对应“代码根本跑不起来”的致命问题;SHORTCODE = 43:内部短路编号,用于报告缓存与去重;- 该类继承自 CodeIssue,构造时接收错误消息和
CodeLocation(代码位置),这也是所有“代码问题”类的公共基类。
检出路径一:ContinueAnalyzer 语句级分析
continue 语句在 AST 中对应 PhpParser\Node\Stmt\Continue_。Psalm 在语句分发处将其路由到专用分析器,见 StatementsAnalyzer.php:
} elseif ($stmt instanceof PhpParser\Node\Stmt\Continue_) {
ContinueAnalyzer::analyze($statements_analyzer, $stmt, $context);
}
核心逻辑全部在 ContinueAnalyzer::analyze 中,可以拆成四个阶段:
1. 解析 continue 的“层数”
$count = $stmt->num instanceof PhpParser\Node\Scalar\Int_? $stmt->num->value : 1;
continue 可携带可选整数(continue 2;),表示跳到第 N 层循环。Psalm 默认取 1。
2. 向上查找目标循环作用域
$loop_scope = $context->loop_scope;
if ($count === 2 && isset($loop_scope->loop_parent_context->loop_scope)) {
$loop_scope = $loop_scope->loop_parent_context->loop_scope;
}
if ($count === 3 && isset($loop_scope->loop_parent_context->loop_scope)) {
$loop_scope = $loop_scope->loop_parent_context->loop_scope;
}
每个循环分析器都会为当前循环创建 LoopScope 并挂到 Context 的 loop_scope 属性上(见 Context.php 中的 public ?LoopScope $loop_scope = null;)。当 continue 2 时,Psalm 通过 loop_parent_context(循环外的父上下文)取出外层循环的 loop_scope,从而正确定位 continue 的目标层级。
3. 无循环上下文时报告问题——但有一个关键豁免
if ($loop_scope === null) {
if (!$context->break_types) {
if (IssueBuffer::accepts(
new ContinueOutsideLoop(
'Continue call outside loop context',
new CodeLocation($statements_analyzer, $stmt),
),
$statements_analyzer->getSource()->getSuppressedIssues(),
)) {
return;
}
}
}
注意 !$context->break_types 这个前置条件。break_types 是一个栈(Context.php 中声明为 public array $break_types = [];),各作用域分析器会往里压入自己:
for/while/do/foreach循环分析器压入'loop'(如 ForeachAnalyzer.php、DoAnalyzer.php、LoopAnalyzer.php);switch的 case 分析器压入'switch'(SwitchCaseAnalyzer.php)。
这正好对齐 PHP 语义:continue 在顶层 switch 中是合法的(表示跳出 switch),因此当 break_types 栈非空(处于 switch 中)时,即使没有循环也不报 ContinueOutsideLoop。而 continue 2 / continue 3 在顶层 switch 中依然越界——这一点由下面的第二条检出路径覆盖。
4. 有循环上下文时:记录控制流动作并合并变量状态
} else {
if ($context->break_types
&& end($context->break_types) === 'switch'
&& $count < 2
) {
$loop_scope->final_actions[] = ScopeAnalyzer::ACTION_LEAVE_SWITCH;
} else {
$loop_scope->final_actions[] = ScopeAnalyzer::ACTION_CONTINUE;
}
// ... 合并 redefined_loop_vars / possibly_redefined_loop_vars ...
}
$context->has_returned = true;
- 如果当前处于“switch 内、目标层仍是循环”的位置(
end($break_types) === 'switch'且count < 2),continue的实际效果是离开 switch 并进入下一轮循环迭代,因此动作记为ACTION_LEAVE_SWITCH;否则记为ACTION_CONTINUE。final_actions会存到LoopScope(见 LoopScope.php 中的final_actions属性),供 LoopAnalyzer 计算循环整体的控制流(例如判断循环体是否“必定 break/continue”)。 - 随后的变量合并逻辑(
getRedefinedVars+Type::combineUnionTypes)处理“continue 跳回迭代末尾时,哪些变量在下一轮可能已被重新赋值”的类型推断;若存在finally_scope,还会同步变量到 finally 块上下文。 - 最后
$context->has_returned = true;表明该分支在此处终止了当前控制流——与return、break的处理一致。
检出路径二:SwitchCaseAnalyzer 的 case 出口分析
第二条报告路径来自 SwitchCaseAnalyzer:
// if we're leaving this block, add vars to outer for loop scope
if ($case_exit_type === 'continue') {
if (!$context->loop_scope) {
if (IssueBuffer::accepts(
new ContinueOutsideLoop(
'Continue called when not in loop',
new CodeLocation($statements_analyzer->getSource(), $case),
),
)) {
return false;
}
}
}
这里报告的消息与路径一不同:'Continue called when not in loop'。它处理的场景是:某个 case 的控制流以 continue 结束($case_exit_type === 'continue'),但该 continue 的目标在 switch 之外(即需要跳到外层循环),而当前根本不存在外层循环。典型例子是测试用例 SwitchTypeTest.php:
'continueIsNotBreak' => [
'code' => '<?php
switch(2) {
case 2:
echo "two\n";
continue 2;
}',
'error_message' => 'ContinueOutsideLoop',
],
测试名 continueIsNotBreak 点出了一个常见误区:很多人以为 switch 里的 continue 2 等价于 break(跳出 switch),但在 PHP 中 continue 2 的目标是 switch 外第 2 层控制结构——没有外层循环时它就是非法的,Psalm 正是借此把它报为 ContinueOutsideLoop。
从源码结构看,case 的退出类型由
ScopeAnalyzer::getControlActions对整个 case 语句序列求值得出,ACTION_CONTINUE(而非ACTION_LEAVE_SWITCH)会被归类为'continue'出口,再进入上述判定;这与ContinueAnalyzer中写入final_actions的动作常量形成了闭环。
支撑模型:Context、break_types 与 LoopScope
把两条路径串起来,Psalm 对循环控制流的状态维护依赖三个协作对象:
Context(src/Psalm/Context.php)break_types:作用类型栈,元素为'loop'或'switch',用于区分“离开的是循环还是 switch”;loop_scope:指向当前最内层循环的LoopScope;finally_scope:try/finally 中的 finally 上下文,continue时需要同步变量类型。
LoopScope(src/Psalm/Internal/Scope/LoopScope.php) 同时持有loop_context(循环体上下文)与loop_parent_context(循环外上下文),并提供final_actions、redefined_loop_vars、possibly_redefined_loop_vars等字段,是continue合并变量类型的落脚点。各循环分析器(ForeachAnalyzer、DoAnalyzer、LoopAnalyzer等)在分析开始时创建LoopScope并挂到上下文中。ContinueAnalyzer/SwitchCaseAnalyzer:前者负责语句级的直接检出与控制流动作记录,后者负责 case 出口层面的二次校验。
这种“栈式作用域 + 循环作用域对象”的模型也解释了 Psalm 为何能区分这些容易混淆的合法/非法边界:
| 代码 | 是否合法(PHP) | Psalm 行为 |
|---|---|---|
顶层 continue; |
否 | ContinueOutsideLoop(ContinueAnalyzer 路径) |
顶层 switch 中裸 continue; |
是(跳出 switch) | 不报(break_types 非空豁免) |
顶层 switch 中 continue 2; |
否 | ContinueOutsideLoop(SwitchCaseAnalyzer 路径,"Continue called when not in loop") |
循环内 switch 中 continue 2; |
是(跳出 switch 并继续外层循环) | 记为 ACTION_LEAVE_SWITCH,不报 |
双层循环中 continue 2; |
是(跳到外层循环末尾) | 通过 loop_parent_context->loop_scope 定位外层作用域 |
测试用例与验证
仓库测试直接覆盖了这两条检出路径:
- 裸
continue报问题:tests/Loop/ForeachTest.php 中continueOutsideLoop用例,代码体只有一个continue;,期望error_message为ContinueOutsideLoop; - switch 越界
continue 2报问题:tests/SwitchTypeTest.php 的continueIsNotBreak用例(见上文代码)。
这两组用例与源码中两条 IssueBuffer::accepts(new ContinueOutsideLoop(...)) 调用点一一对应,说明当前实现中该问题只有这两个发射点(可通过在 src 下检索 ContinueOutsideLoop 确认,另两处为 PreloaderList.php 中的预加载列表与 issue 类定义本身)。
实践建议
- 看到此问题应当视为确定性 bug:ERROR_LEVEL 7 的问题意味着代码无法通过 PHP 编译,无需讨论误报;修复方式就是删除该
continue或为其补齐循环上下文。 - switch 中的
continue要特别小心:continue(无数字)在 switch 中是“跳出 switch”,continue 2才是“跳到外层循环”;把continue 2误当break使用是最常见的触发来源。 - 抑制方式:如确有生成代码等无法修改的场景,可按 Psalm 通用的抑制机制(
psalm-suppress=ContinueOutsideLoop)在配置或 docblock 中处理;由于报告经过getSuppressedIssues()过滤(见 ContinueAnalyzer.php),标准抑制手段对该问题有效。