Psalm UndefinedFunction 错误详解:触发机制、命名空间解析与配置修复方案

原创2026-10-12 17:45:281,411 阅读
文章标签:开发工具代码质量质量保障

Psalm UndefinedFunction 错误详解:触发机制、命名空间解析与配置修复方案

Psalm 是 PHP 应用的静态分析工具,当代码中引用了不存在的函数时会报告 UndefinedFunction 错误。本文以 docs/running_psalm/issues/UndefinedFunction.md 为主线,结合源码实现(CallAnalyzer.php)、配置解析逻辑(Config.php)与真实测试用例,完整讲解该错误的触发条件、底层判定流程、命名空间解析规则,以及通过 composer.json、enableExtensions、allFunctionsGlobal 等配置的修复与抑制方法,帮助你在实际项目中快速定位并解决“函数不存在”类问题。

什么是 UndefinedFunction

根据官方 issue 文档,UndefinedFunction 在引用一个不存在的函数时被抛出,最典型的例子:

<?php

foo();

Psalm 在分析时无法在项目代码、Composer 依赖或内置函数表中找到名为 foo 的函数,因此报告该错误。

该错误还会在使用了扩展函数,但该扩展既未加入 composer.json 的 requirements,也未加入 enableExtensions 配置键时被抛出。例如调用了 decimal、pdo 等扩展提供的函数,而分析环境中没有启用对应扩展的 stub。

源码级触发机制:函数存在性判定流程

UndefinedFunction 的核心判定位于 CallAnalyzer.php 的 checkFunctionExists() 方法。整个判定流程可分为两个阶段:

阶段一:函数是否被 Psalm 认知

$cased_function_id = $function_id;
$function_id = strtolower($function_id);

$codebase = $statements_analyzer->getCodebase();

if (!$codebase->functions->functionExists($statements_analyzer, $function_id)) {
    // ... 判定逻辑
}

Psalm 先将函数名转为小写(PHP 函数名不区分大小写),然后通过 $codebase->functions->functionExists() 查询函数是否已知。函数来源包括:被扫描的项目源码、Composer 依赖、内置的 callmap/stub(见 dictionaries/ 与 stubs/ 目录)。

若函数确实不存在,则进入根命名空间回退逻辑:

$root_function_id = (string) preg_replace('/.*\\\/', '', $function_id);

if ($can_be_in_root_scope
    && $function_id !== $root_function_id
    && $codebase->functions->functionExists($statements_analyzer, $root_function_id)
) {
    $function_id = $root_function_id;
} else {
    IssueBuffer::maybeAdd(
        new UndefinedFunction(
            'Function ' . $cased_function_id . ' does not exist'
                . ', consider enabling the allFunctionsGlobal config option if scanning legacy codebases',
            $code_location,
            $function_id,
        ),
        $statements_analyzer->getSuppressedIssues(),
    );
    return false;
}

也就是说,当调用的是命名空间内函数(如 Foo\bar()),若该函数在全局命名空间存在同名函数,Psalm 会回退使用全局版本而不报错;只有回退也找不到时,才报告 UndefinedFunction,错误消息中还会附带提示:在扫描 legacy 代码库时可考虑启用 allFunctionsGlobal 配置选项。

阶段二:PHP 版本不匹配判定

即便函数被 Psalm 认知(stub 签名已加载),仍可能因为当前分析版本过旧而报告 UndefinedFunction。源码中通过 stub 上的 @since 信息(since_php_version_id)判定:

$since_php_version_id = $function_storage->since_php_version_id;

$is_native = $function_storage->location === null
    || pathinfo($function_storage->location->file_path, PATHINFO_EXTENSION) === 'phpstub';

if ($since_php_version_id === null && $is_native) {
    $since_php_version_id = InternalCallMapHandler::getIntroducingPhpVersionId($function_id);
}

if ($since_php_version_id !== null
    && $is_native
    && ($codebase->getGuardedPhpVersionId($context) ?? $codebase->analysis_php_version_id)
        < $since_php_version_id
    && !$codebase->functions->isDeclaredInCode($function_id)
) {
    IssueBuffer::maybeAdd(
        new UndefinedFunction(
            'Function ' . $cased_function_id . ' '
                . $codebase->getUnavailableSymbolMessageSuffix($since_php_version_id),
            $code_location,
            $function_id,
        ),
        $statements_analyzer->getSuppressedIssues(),
    );
}

这段逻辑的含义是:当一个函数是在较新 PHP 版本中引入的原生函数(来自 stub 或版本化 callmap,见 dictionaries/CallMap_70.php 至 CallMap_85.php),而当前分析的 phpVersion 早于该版本,且代码中没有通过 polyfill(在 PHP 代码中声明同名函数)使其可用时,Psalm 同样会报告 UndefinedFunction——这是为了提醒你该调用在当前目标 PHP 版本下会运行失败。值得注意的是,此分支不会把调用当作未知处理,stub 签名仍会参与后续分析。

错误级别与报告属性

UndefinedFunction 的 issue 定义位于 src/Psalm/Issue/UndefinedFunction.php:

final class UndefinedFunction extends FunctionIssue
{
    public const ERROR_LEVEL = -1;
    public const SHORTCODE = 21;
}
  • ERROR_LEVEL = -1:表示该错误属于“始终报告(Always errors)”级别。根据 docs/running_psalm/error_levels.md,Psalm 的 error level 从 1(最严格)到 8(最宽松),默认 level 2;而 -1 级别的问题误报率极低、代表确定性缺陷(如 UndefinedClass、UndefinedVariable),无法通过调低 error level 来抑制。
  • SHORTCODE = 21:这是该 issue 在 Psalm 中的唯一数字标识,用于 JSON/SARIF 等机器可读报告中定位错误类型,也用于 baseline 文件中的条目匹配。

常见触发场景与测试佐证

场景一:直接调用未定义函数

<?php

foo();

场景二:以字符串形式回调未定义函数

Psalm 同样会检查以字符串形式传递的回调。测试用例 tests/FunctionCallTest.php 验证了这一点:

array_map(
    "undefined_function",
    [1, 2, 3]
);

这里 array_map 的回调是字符串 "undefined_function",Psalm 仍会解析该字符串并报告 UndefinedFunction。

场景三:命名空间解析失败

命名空间下函数解析是误报高发区。测试 tests/NamespaceTest.php 覆盖了两种典型情况:

  • 在全局命名空间调用定义于命名空间 A 中的 foo():
namespace A {
    function foo() {}
}
namespace {
    foo(); // UndefinedFunction:全局命名空间中不存在 foo
}
  • 在命名空间 A 内调用 \A\foo(),但 foo 实际定义在全局命名空间:
namespace {
    function foo() {}
}
namespace A {
    \A\foo(); // UndefinedFunction:A 命名空间内不存在 foo
}

场景四:跨文件 include 后的命名空间不匹配

测试 tests/IncludeTest.php 展示了 require 引入文件后命名空间不匹配的情况:

// file1.php(全局命名空间)
function fooFoo(): void {}

// file2.php(命名空间 Foo)
namespace Foo;

require("file1.php");

\Foo\fooFoo(); // UndefinedFunction:file1.php 中的 fooFoo 定义在全局命名空间

这提醒我们:require/include 引入的全局函数,在被引入文件内通过限定命名空间名调用时会被判定为不存在。

如何修复:配置层面的解决方案

方案一:通过 composer.json 声明扩展

Psalm 默认只启用 composer.json 中 require/require-dev 里以 ext- 前缀声明的扩展。配置解析逻辑见 src/Psalm/Config.php:

if (str_starts_with((string) $required, "ext-")) {
    $required_extensions[strtolower(substr((string) $required, 4))] = true;
}

因此,在使用某扩展函数前,先在 composer.json 中声明:

{
    "require": {
        "ext-pdo": "*",
        "ext-decimal": "*"
    }
}

方案二:使用 enableExtensions / disableExtensions 配置

若不便修改 composer.json,可在 Psalm 配置文件中显式启用扩展。根据 docs/running_psalm/configuration.md:

<psalm>
    <enableExtensions>
        <extension name="decimal"/>
        <extension name="pdo"/>
    </enableExtensions>
</psalm>

与之对应,<disableExtensions> 可显式禁用扩展(默认只启用 composer.json 要求的扩展,所以禁用场景较少):

<psalm>
    <disableExtensions>
        <extension name="gmp"/>
    </disableExtensions>
</psalm>

配置解析实现位于 src/Psalm/Config.php:enableExtensions 会将对应扩展在 $config->php_extensions 中置为 true,disableExtensions 置为 false。文档还提示:Psalm 已内置部分扩展 stub(见 stubs/extensions/ 目录,如 decimal.phpstub、pdo.phpstub、gmp.phpstub 等),可通过 composer.json 或 enableExtensions 配置键启用,无需额外安装 stub 文件。

方案三:allFunctionsGlobal 应对 legacy 代码库

当项目大量使用 require/include 而非 Composer autoloader 时,Psalm 默认无法跨文件看到这些函数,导致大量 UndefinedFunction 误报。此时可在配置中开启(docs/running_psalm/configuration.md):

<psalm
    allFunctionsGlobal="true"
>

开启后,Psalm 会把所有被扫描文件中声明的函数视为对所有文件可用(即便它们未被 Composer autoloader 加载),默认值为 false。该选项正是 checkFunctionExists 错误消息中“consider enabling the allFunctionsGlobal config option if scanning legacy codebases”提示所指的修复路径。

方案四:校准 phpVersion 消除版本差异误报

当目标 PHP 版本低于某原生函数引入版本时,Psalm 会报告 UndefinedFunction(见上文阶段二)。在 psalm.xml 中显式声明项目实际运行的 PHP 版本可以避免误判:

<psalm
    phpVersion="8.1"
>

使分析版本与实际部署环境一致后,凡在 PHP 8.1 中可用的函数都不会再因版本差异被误报。若你确实需要在旧版本环境中使用新函数,则应在代码中提供 polyfill 声明(isDeclaredInCode 检查通过后即不报错)。

方案五:通过 stubs 提供自定义函数签名

如果依赖了反射环境不可见(如未安装的内部包)的函数,可使用 <stubs> 配置提供签名描述:

<psalm>
    <stubs>
        <file name="path/to/file.php" />
    </stubs>
</psalm>

详细说明见 docs/running_psalm/configuration.md。stub 中的函数声明被 Psalm 认知后,functionExists 检查即可通过。

如何抑制 UndefinedFunction

由于该问题属于“始终报告”级别,无法通过降低 error level 抑制,但仍有三种官方支持的方式:

方式一:局部注解抑制

在调用语句前添加 @psalm-suppress 注解。测试用例 tests/IssueSuppressionTest.php 展示了标准写法:

function verify_return_type(): DateTime {
    /** @psalm-suppress UndefinedFunction */
    unknown_function_call();

    return new DateTime();
}

方式二:issueHandlers 全局或按函数抑制

在 psalm.xml 的 <issueHandlers> 中全局抑制该问题:

<psalm>
    <issueHandlers>
        <UndefinedFunction>
            <errorLevel type="suppress"/>
        </UndefinedFunction>
    </issueHandlers>
</psalm>

更精细的写法是按函数名抑制。测试 tests/Config/ConfigTest.php 验证了 referencedFunction 的用法:

<psalm>
    <issueHandlers>
        <UndefinedFunction>
            <errorLevel type="suppress">
                <referencedFunction name="zzz"/>
            </errorLevel>
        </UndefinedFunction>
    </issueHandlers>
</psalm>

这样只有 zzz() 这个特定函数调用会被忽略,其余未定义函数仍会报告。

方式三:加入错误基线(baseline)

将存量问题一次性写入 baseline 文件,使后续只报告新增问题。相关操作方式见 docs/running_psalm/dealing_with_code_issues.md 与 docs/running_psalm/error_levels.md。baseline 中 UndefinedFunction 条目以 SHORTCODE = 21 作为机器标识。

与相邻 issue 的区分

在排查“函数/方法不存在”类错误时,注意与以下 issue 区分:

  • UndefinedMethod:针对 $obj->method() 形式的不存在方法调用(而非函数);
  • UndefinedClass:针对不存在的类引用,通常也会连带产生方法调用错误;
  • PossiblyNullFunctionCall / PossiblyInvalidFunctionCall:函数调用目标可能是 null 或非可调用类型,见 tests/FunctionCallTest.php,属于变量类型不确定导致的“可能”级别问题,而非函数本身不存在。

小结

UndefinedFunction 是 Psalm 中最直接、误报率最低的错误之一:只要函数在项目源码、依赖或内置 callmap/stub 中都不存在,或在目标 PHP 版本下不可用,就会以“始终报告”级别抛出。实际项目中的处理优先级建议为:

  1. 确认函数确实存在或缺失,补全代码/依赖;
  2. 使用扩展函数时,同步在 composer.json 或 <enableExtensions> 中声明扩展;
  3. legacy 代码库大量 require/include 时开启 allFunctionsGlobal;
  4. 版本差异场景校准 phpVersion 或提供 polyfill;
  5. 确属无法解决的外部调用时,使用 @psalm-suppress、issueHandlers 或 baseline 精准抑制。
登录后查看全文
psalm