企业官网建设流程全解析

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

Psalm 是 PHP 生态中的静态分析工具，能够在不运行代码的前提下发现潜在的错误与安全漏洞。本文聚焦于其内置的TooFewArguments问题类型——当调用函数或方法时传入的实参数量少于被调函数所声明的形参数量，Psalm 就会在对应代码位置报告该问题。读完本文，你将掌握TooFewArguments的完整触发场景、底层检测算法（包括命名参数与数组解包的复杂处理）、运行级错误定位方法，以及通过 docblock、配置文件和 baseline 三种途径管理该问题的实战方案。

问题定义：什么是 TooFewArguments

TooFewArguments在调用函数时，若传入的实参数量少于函数声明的形参数量，Psalm 即会报告此问题。官方文档给出的最小触发示例为：

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

在上面的代码中，foo声明了一个必填参数$a，而调用处foo()没有传入任何参数，Psalm 便会在此位置抛出TooFewArguments。

与运行期异常的区别

这类错误在 PHP 运行期会直接抛出ArgumentCountError（PHP 8 起）或以警告形式中断执行，属于确定性的程序缺陷。Psalm 的价值在于：静态分析阶段就能在 CI 中拦截它，无需等到代码真正执行。这一点在仓库的返回类型提供器 SprintfReturnTypeProvider.php 中体现得尤为直观——该提供器通过构造占位符与实际参数数量不一致的调用，捕获ArgumentCountError异常后将其转换为TooFewArguments报告，说明 Psalm 自身也把"实参不足"与运行期ArgumentCountError视为同一类问题的静态等价物。

问题类实现：错误级别与短码

TooFewArguments问题在源码中定义于 TooFewArguments.php：

<?php declare(strict_types=1); namespace Psalm\Issue; /** * @api */ final class TooFewArguments extends ArgumentIssue { public const ERROR_LEVEL = -1; public const SHORTCODE = 25; }

两个关键常量决定了它的行为特性：

• ERROR_LEVEL = -1：表示该问题属于"始终报错"类别。根据 error_levels.md 的说明，这类问题误报率极低、代表确定的程序缺陷，无法通过调整 error level（1～8）来降级或屏蔽。只有@psalm-suppress、配置文件issueHandlers或 baseline 才能压制它。在 error_levels.md 的"始终视为错误"清单中，TooFewArguments与UndefinedClass、UndefinedVariable等并列。
• SHORTCODE = 25：Psalm 为每个问题分配的唯一短码。在 IssueData.php 中可以看到，短码会被格式化为三位数并用于生成指向问题说明页的链接，方便在报告输出中快速溯源。

此外，TooFewArguments继承自 ArgumentIssue.php，该抽象基类为所有"实参类问题"（如TooManyArguments、InvalidArgument、NullArgument等）增加了function_id属性，并在构造时统一将函数名转为小写存储——这保证了同一函数无论以何种大小写形式被调用，报告中的标识都能被规范匹配。

触发场景详解：不只是普通函数调用

虽然"形参多于实参"是最直观的场景，但从源码看，TooFewArguments在 Psalm 中有多个独立触发点，覆盖了用户函数、内置函数、方法调用与特殊语法结构：

1. 用户自定义函数与方法的实参校验

核心检测逻辑位于 ArgumentsAnalyzer.php 的checkArgCount方法。当count($args) < count($function_params)时，Psalm 会遍历实参，将已匹配的形参从待校验列表中剔除，然后对剩余形参逐个检查：

// 剩余未匹配形参中，若有必填（非可选、非可变参数）项，则报告 TooFewArguments foreach ($function_params as $i => $param) { if (!$param->is_optional && !$param->is_variadic) { IssueBuffer::maybeAdd( new TooFewArguments( 'Too few arguments for ' . $cased_method_id . ' - expecting ' . $param->name . ' to be passed', $code_location, (string)$method_id, ), $statements_analyzer->getSuppressedIssues(), ); continue; } // ... 对带默认值的参数进行类型推断与模板替换 }

这段代码揭示了几条重要规则：

• 可选参数（带默认值）不触发：foo(string $a = 'x')即使不传参也合法，因为is_optional为真；
• 可变参数不触发：foo(string ...$args)可以接受零个或多个实参；
• 报告信息可定位到具体缺失的参数名：例如错误消息Too few arguments for foo - expecting a to be passed会明确指出缺失的是哪个形参，这在多参数函数排错时非常有用；
• 解包（unpack）实参参与数量推导：当实参是...$arr形式时，Psalm 会根据数组类型推导展开后的确定数量——TKeyedArray（数组形状）按属性数量计、TNonEmptyArray按记录的 count 计、never类型按 0 计；只有能确定稳定数量时才继续判定，否则放弃检查以避免误报；
• 命名参数（named arguments）按名称匹配：命名实参会从形参列表中按名字剔除对应项，这意味着以命名方式跳过了某个必填参数，同样会触发TooFewArguments。

2. 方法调用：基于调用结果的结构化报告

对于$obj->method(...)形式的方法调用，检测发生在 MethodCallAnalyzer.php。方法调用分析器先计算出too_few_arguments标记与方法 ID 列表，再统一上报：

if ($result->too_few_arguments && $result->too_few_arguments_method_ids) { $error_method_id = $result->too_few_arguments_method_ids[0]; IssueBuffer::maybeAdd( new TooFewArguments( 'Too few arguments for method ' . $error_method_id . ' saw ' . count($stmt->getArgs()), new CodeLocation($source, $stmt->name), (string) $error_method_id, ), $statements_analyzer->getSuppressedIssues(), ); }

注意这里与函数调用报告的不同：消息格式为Too few arguments for method ClassName::method saw N，同时CodeLocation指向方法名（$stmt->name）而非整个调用表达式，便于精确定位。

3. 特殊语法结构：clone 与 get_class()

• clone语句：在 CloneAnalyzer.php 中，当 clone 语句缺少被克隆的对象实参（如 PHP 8 命名参数语法下clone(withProperties: [...])这类写法）时，会报告Too few arguments for clone - expecting object to be passed。
• get_class()：在 ArgumentsAnalyzer.php 中，get_class()无参数调用仅在类作用域内合法；在类外调用会报告Cannot call get_class() without argument outside of class scope。

4. 内置函数与 CallMap 校验

对于 PHP 内置函数，Psalm 依赖dictionaries/目录下的 CallMap 文件（如 CallMap_84.php）声明的参数签名进行校验。测试用例 FunctionCallTest.php 展示了preg_match的检测：

preg_match('/adsf/'); // TooFewArguments - somefile.php:2:21 - Too few arguments for preg_match - expecting subject to be passed

preg_match至少需要两个参数（pattern 与 subject），这里仅传一个，Psalm 依据 CallMap 精确指出缺失的是subject参数。

5. 高阶函数：array_map 与 array_filter 系列

在 ArgumentsAnalyzer.php 中，array_map与array_filter系列函数有专门的数量下限校验：array_map至少需要 2 个实参（回调 + 数组），array_filter系列至少 1 个。测试 ArrayFunctionCallTest.php 验证了这一点：

function foo(int $i, string $s) : bool { return true; } array_map("foo", [1, 2, 3]); // TooFewArguments：回调 foo 需要 2 个参数，但只传了 1 个数组

实践验证：结合测试用例理解判定逻辑

仓库测试是理解该问题行为的最佳教材，以下用例覆盖了主要分支：

特别值得关注的是命名参数场景（ArgTest.php）：

class User { public function __construct( protected string $name, protected string $problematicOne, protected string $id = "", ){} } new User( name: "John", id: "asd", ); // TooFewArguments：必填参数 problematicOne 未被传入

这里id有默认值所以合法，但必填的problematicOne被跳过了——即使 PHP 运行期会因此抛ArgumentCountError，Psalm 在静态阶段就已识别出来。

问题管理与修复策略

由于TooFewArguments属于"始终报错"级别，无法通过调低 error level 屏蔽，管理它的手段集中在以下三种：

1. 从根本上修复：补全缺失实参

最直接的修复是补齐缺失的参数。对于带默认值的形参，若业务上允许缺省，则保持不传是合法的（Psalm 不会报告）；若参数确实必填，则应补传：

function foo(string $a) : void {} foo('bar'); // 修复：传入必填参数

2. Docblock 级抑制

如果某个调用点确实有意为之（例如通过魔术方法或回调签名不匹配的兼容写法），可在函数或语句的 docblock 中使用@psalm-suppress。根据 dealing_with_code_issues.md，支持函数级与行级两种粒度：

<?php /** * @psalm-suppress TooFewArguments */ function wrapper() : void { foo(); // 该函数内的调用被抑制 }

<?php /** * @psalm-suppress TooFewArguments */ foo();

若需要一次性抑制所有问题，可使用@psalm-suppress all。

3. 配置文件级抑制

在psalm.xml中使用<issueHandlers>标签可按目录、文件粒度抑制（详见 dealing_with_code_issues.md）：

<issueHandlers> <TooFewArguments> <errorLevel type="suppress"> <directory name="tests" /> </errorLevel> </TooFewArguments> </issueHandlers>

也可以仅将级别降为info（打印但不中断构建）：

<issueHandlers> <TooFewArguments errorLevel="info" /> </issueHandlers>

4. Baseline 固化存量问题

对于存量代码中大量存在、暂时无法一次性修复的TooFewArguments，推荐使用 baseline 机制（见 dealing_with_code_issues.md）：

vendor/bin/psalm --set-baseline

首次生成 baseline 后，存量问题被"祖父化"不再报错，而新增代码中出现同类问题仍会被正常报告，实现渐进式修复。

与其他实参问题的区分

实参数量校验是一个完整的双端体系，理解TooFewArguments的同时也应了解它的对称问题：

• TooFewArguments（本文）：实参少于必填形参，始终报错；
• TooManyArguments：实参多于形参且函数非可变参数。它定义于 TooManyArguments.md，ERROR_LEVEL为 1——这意味着在默认 error level 2 下它是报错，但在 level 5 及更宽松级别下会被降级为 info（见 error_levels.md 的级别对照表）。其检测逻辑同样位于 ArgumentsAnalyzer.php，报告形如Too many arguments for fooFoo - expecting 1 but saw 2（测试见 FunctionCallTest.php）。

两者在checkArgCount中共享同一套参数匹配框架，但TooFewArguments因为ERROR_LEVEL = -1而拥有更高的强制级别，这反映了设计者的判断：漏传参数几乎总是确定性缺陷，而多传参数（在历史 PHP 版本中）更可能存在兼容场景。

小结

TooFewArguments是 Psalm 实参校验体系中强制级别最高的问题类型，覆盖普通函数、方法、内置函数、clone、get_class以及array_map/array_filter系列等全部调用形态。其检测核心 checkArgCount 不仅比较数量，还正确处理了默认参数、可变参数、命名参数与数组解包等现代 PHP 语法；配套的 FunctionCallTest.php、ArgTest.php 与 ArrayFunctionCallTest.php 提供了覆盖各分支的回归保障。在 CI 流程中遇到该报告时，优先按错误消息中"expecting X to be passed"的提示补全参数，确属有意为之再使用抑制或 baseline 手段管理。

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