Psalm 静态分析：NullFunctionCall 问题详解——把 `null` 当作可调用函数的检测与修复

• 开发工具
• 代码质量
• 质量保障

导读

NullFunctionCall是 Psalm 在 PHP 静态分析中报告的一类问题：当代码把一个值为null的变量当作可调用函数（callable）去执行时触发。本指南以官方问题文档 NullFunctionCall 为核心，结合源码实现与测试用例，完整讲解该问题的触发条件、错误级别、与兄弟问题PossiblyNullFunctionCall的差异、底层分析原理，以及从配置抑制到基线管理的完整实战修复方案。

问题定义：什么是 NullFunctionCall

按照官方文档 NullFunctionCall 的定义：

Emitted when trying to usenullas acallable（当尝试把null用作callable时触发）。

在 PHP 中，变量可以像函数一样被调用（variable functions / first-class callable），例如：

<?php $arr = null; echo $arr();

上面这段代码中，$arr被赋值为null，随后又通过$arr()以函数调用的方式执行。在运行时，PHP 会抛出Error: Value of type null is not callable。Psalm 会在静态分析阶段提前发现这一确定性错误并报告NullFunctionCall，从而在代码真正执行前拦截该缺陷。

这类问题最典型的出现场景包括：

• 把回调变量初始化为null后忘记赋值就调用；
• 从可能返回null的数组、配置项或函数结果中取出回调再直接调用；
• 闭包/函数类型变量被错误地赋值为null后执行。

错误级别：为什么它总是致命错误

在 Psalm 的错误级别体系中，每一个 issue 都通过两个常量定义其行为，见 NullFunctionCall.php：

final class NullFunctionCall extends CodeIssue { public const ERROR_LEVEL = -1; public const SHORTCODE = 93; }

• ERROR_LEVEL = -1表示该问题属于「始终作为错误处理」的特殊类别；
• SHORTCODE = 93是该问题的唯一短码，用于输出、基线文件与插件系统标识。

在 error_levels.md 中，NullFunctionCall与UndefinedClass、UndefinedVariable、InvalidThrow等一起被列在Always treated as errors（始终视为错误）类别下。这类问题误报率极低，代表确定的缺陷，无法通过调高errorLevel将其降级为 info，只能通过显式抑制或基线方式处理。

Psalm 的错误级别从 1（最严格）到 8（最宽松），默认级别为 2，可以在 configuration.md 中的errorLevel配置项调整：

<psalm errorLevel="[int]" />

级别越高，更多问题被降级为 info（非阻塞）。但无论级别如何设置，NullFunctionCall始终保持错误状态。

与 PossiblyNullFunctionCall 的区别

NullFunctionCall有一个经常被混淆的兄弟问题：PossiblyNullFunctionCall（文档见 PossiblyNullFunctionCall），它的定义是：

Emitted when trying to call a function on a value that may be null（当尝试对一个可能为null的值进行函数调用时触发）。

两者的核心差异在于确定性与类型收敛：

PossiblyNullFunctionCall的官方示例：

<?php function foo(?callable $a) : void { $a(); }

参数$a的类型是callable|null，调用时只有null分支会崩溃，因此这是「可能」而非「确定」的错误。它的ERROR_LEVEL = 3（见 PossiblyNullFunctionCall.php），意味着在 errorLevel 1–3 时作为错误，在 errorLevel 4 及更宽松时降级为 info。

源码级原理：Psalm 是如何判定并报告的

从源码结构看，这两个问题都在函数调用分析器 FunctionCallAnalyzer.php 的getAnalyzeNamedExpression()方法中触发。该方法先对「被调用方表达式」（即函数名位置的表达式）进行类型分析，随后基于类型结果分派问题，核心逻辑如下（对应源码第 697–718 行）：

if ($stmt_name_type = $statements_analyzer->node_data->getType($function_name)) { if ($stmt_name_type->isNull()) { IssueBuffer::maybeAdd( new NullFunctionCall( 'Cannot call function on null value', new CodeLocation($statements_analyzer->getSource(), $stmt), ), $statements_analyzer->getSuppressedIssues(), ); return $function_call_info; } if ($stmt_name_type->isNullable()) { IssueBuffer::maybeAdd( new PossiblyNullFunctionCall( 'Cannot call function on possibly null value', new CodeLocation($statements_analyzer->getSource(), $stmt), ), $statements_analyzer->getSuppressedIssues(), ); } // ... 后续继续验证 callable / 闭包 / 模板参数等原子类型 }

其判定链可以概括为：

1. 类型提取：通过node_data->getType($function_name)取得被调用表达式的静态类型；
2. 精确 null 判定：调用isNull()，若类型确证为null，立即报告NullFunctionCall并终止后续分析（return），因为该调用确定失败；
3. 可空判定：若类型是 nullable（如callable|null、Closure|null），报告PossiblyNullFunctionCall，但不终止分析，继续检查其余非空分支的类型是否合法（如是否为TCallable、TClosure、TTemplateParam等原子类型，见源码第 720 行起的原子类型循环）；
4. 统一出口：所有报告都经过IssueBuffer::maybeAdd，它会同时考虑该位置被抑制的 issue 列表（getSuppressedIssues()），因此源码层面的抑制机制在进入maybeAdd之前就已生效。

值得注意的细节：两个 issue 的消息文本分别为Cannot call function on null value和Cannot call function on possibly null value，这也直接体现在 CLI 与各种报告格式（text、json、sarif、github 等）的输出中，可作为检索定位依据。

测试用例佐证

仓库测试为这两个问题的行为提供了可复现证据：

• FunctionCallTest.php 第 2724–2729 行的possiblyNullFunctionCall用例：

  $a = rand(0, 1) ? function(): void {} : null; $a();

  该用例断言错误消息为PossiblyNullFunctionCall。由于rand(0, 1)使闭包与null形成联合类型，Psalm 无法确证非空，因而报告「可能」版本而不是「确定」版本。

• ClosureTest.php 第 1165 行起的possiblyNullFunctionCall用例，针对@var Closure|null类型的闭包变量递归自调用场景，验证了Closure|null联合类型下的同样行为。

这两个用例共同说明：NullFunctionCall（确定）只有在类型系统能够完全排除非空分支（即类型精确收敛为null）时才会出现；只要存在callable/Closure分支，就只会报告PossiblyNullFunctionCall。

实战修复：如何消除 NullFunctionCall

1. 保证调用前变量非空

对于确定性的NullFunctionCall，最直接的修复是确保变量在调用点一定持有合法回调：

<?php // 反例：触发 NullFunctionCall $arr = null; echo $arr(); // 修复：先赋值真正的可调用值再调用 $arr = static function (): string { return 'hello'; }; echo $arr();

2. 对可空回调做空值防护

当回调可能为null时，使用is_callable()或空值判断收窄类型，可把问题降级为可安全运行的代码：

<?php /** @var callable|null $callback */ $callback = $maybeConfig['handler'] ?? null; if (is_callable($callback)) { $callback(); }

类型收窄后，Psalm 在if分支内能确认$callback为 callable，不再报告PossiblyNullFunctionCall。

3. 通过 docblock 局部抑制

若确属无法避免的调用点（例如第三方回调协议保证非空但静态分析无法证明），可在函数 docblock 中抑制，详见 dealing_with_code_issues.md：

<?php /** * @param callable|null $a * @psalm-suppress PossiblyNullFunctionCall */ function foo($a) : void { $a(); }

也可把抑制注解写在具体语句前的注释中，实现行级抑制：

<?php /** @psalm-suppress PossiblyNullFunctionCall */ $callback();

如需在某个函数内屏蔽全部问题，可以使用@psalm-suppress all。

4. 通过配置批量抑制

在 configuration.md 对应的 XML 配置中，可以对全局或特定目录/文件抑制：

<psalm> <issueHandlers> <PossiblyNullFunctionCall errorLevel="suppress" /> <errorLevel type="suppress"> <directory name="src/legacy" /> <file name="src/legacy/handler.php" /> </errorLevel> </issueHandlers> </psalm>

5. 使用基线管理存量问题

对于引入 Psalm 时存量代码中的大量Possibly*问题，推荐使用基线而非逐个抑制。在 dealing_with_code_issues.md 中给出的流程为：

vendor/bin/psalm --set-baseline=psalm-baseline.xml # 生成当前错误快照 vendor/bin/psalm --use-baseline=psalm-baseline.xml # 运行分析时忽略基线内问题 vendor/bin/psalm --update-baseline # 修复部分问题后刷新基线

基线文件路径也可以在配置中指定：

<psalm errorBaseline="./psalm-baseline.xml" />

注意：--update-baseline只移除已修复的问题、不会新增问题；需要纳入新问题时请使用--set-baseline=...重新生成。临时忽略基线运行可用--ignore-baseline。

6. 关于 suppress 的严格性说明

在 dealing_with_code_issues.md 中还有一条与抑制相关的配置提醒：当reportMixedIssues之外的另一项行为被关闭时，Psalm 将不会把低于errorLevel的 issue 视为info（而是直接抑制），这虽可显著提升大型项目的分析速度，但会阻止 Psalm 统计或建议修复被抑制的问题。因此对PossiblyNullFunctionCall这类「可能」错误，优先采用类型收窄或基线，而不是大面积 suppress。

小结

NullFunctionCall是 Psalm 中误报率极低、始终按错误处理的确定性缺陷，标志着「把null当作函数调用」这一必然崩溃的写法；其「可能」形态由PossiblyNullFunctionCall在 errorLevel 3 及以下报告。从 FunctionCallAnalyzer.php 的isNull()/isNullable()判定链，到 FunctionCallTest.php、ClosureTest.php 的测试用例，再到 error_levels.md、configuration.md 与 dealing_with_code_issues.md 的配套文档，都指向同一条实践准则：在调用任何可变函数前先证明它非空——要么用类型收窄让分析器确认，要么用基线记录存量债，把静态分析的确定性优势转化为线上运行的安全保障。

• 开发工具
• 代码质量
• 质量保障