Psalm 的 ContinueOutsideLoop 问题详解:为什么循环外 continue 会被静态检出及其源码实现

原创2026-10-09 14:52:181,978 阅读
文章标签:开发工具代码质量质量保障

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 continue statement 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 = [];),各作用域分析器会往里压入自己:

这正好对齐 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 对循环控制流的状态维护依赖三个协作对象:

  1. Context(src/Psalm/Context.php)
    • break_types:作用类型栈,元素为 'loop' 或 'switch',用于区分“离开的是循环还是 switch”;
    • loop_scope:指向当前最内层循环的 LoopScope;
    • finally_scope:try/finally 中的 finally 上下文,continue 时需要同步变量类型。
  2. 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 并挂到上下文中。
  3. 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 类定义本身)。

实践建议

  1. 看到此问题应当视为确定性 bug:ERROR_LEVEL 7 的问题意味着代码无法通过 PHP 编译,无需讨论误报;修复方式就是删除该 continue 或为其补齐循环上下文。
  2. switch 中的 continue 要特别小心:continue(无数字)在 switch 中是“跳出 switch”,continue 2 才是“跳到外层循环”;把 continue 2 误当 break 使用是最常见的触发来源。
  3. 抑制方式:如确有生成代码等无法修改的场景,可按 Psalm 通用的抑制机制(psalm-suppress=ContinueOutsideLoop)在配置或 docblock 中处理;由于报告经过 getSuppressedIssues() 过滤(见 ContinueAnalyzer.php),标准抑制手段对该问题有效。
登录后查看全文
psalm