PHPStan function.duplicate 错误详解：同名函数重复声明检测与修复

• 开发工具
• 代码质量
• 静态分析

function.duplicate是 PHPStan 静态分析工具在分析过程中发现同一函数名在多个文件中被重复声明时报告的错误标识符（identifier）。本文基于 website/errors/function.duplicate.md 展开，讲解该错误的触发场景、底层规则实现（DuplicateFunctionDeclarationRule）、PHP 语言层面的成因，以及两种标准的修复方式，帮助你在实际项目中快速定位并消除这类重复声明问题。

错误概览

从文档生成机制看，本文件属于 website/errors 目录下按错误标识符组织的文档体系。该目录中的每份文档都遵循统一结构（见 website/errors/CLAUDE.md）：包含title、shortDescription、ignorable三个 frontmatter 字段，正文由## Code example、## Why is it reported?、## How to fix it三部分组成。function.duplicate标识符与class.duplicate、interface.duplicate、trait.duplicate、enum.duplicate属于同一"重复声明"系列（分别对应类、接口、trait、枚举的重复声明检测）。

触发场景：跨文件的重复函数声明

该错误在被分析代码库的多个文件中声明了同名函数时触发。文档给出了最小复现示例：

// file1.php <?php declare(strict_types = 1); namespace App; function helper(): void { }

// file2.php <?php declare(strict_types = 1); namespace App; function helper(): void { }

两个文件都位于App命名空间，且都声明了同名函数helper()。PHP 语言本身规定：除条件声明外，函数名在 PHP 中是全局唯一的，同一个命名空间内不允许声明两个同名函数。当 PHPStan 扫描到这类重复声明时，就会报告function.duplicate。

需要注意的是，虽然这个错误通常源于项目自身的代码重复，但文档特别指出，它的典型触发位置是被注册的stub 文件（stub files）中。Stub 文件是 PHPStan 提供的用于"覆盖第三方 PHPDoc 错误声明"的机制——当第三方依赖库的 PHPDoc 不准确时，你可以通过 stub 文件提供更准确的函数、类或方法的签名（相关概念见 website/src/_posts/solving-phpstan-no-value-type-specified-in-iterable-type.md，配置项stubFiles说明见 website/src/config-reference.md）。如果你为同一个函数编写了多个 stub，或者项目代码与 stub 中声明的函数重复，就会触发该错误。

底层规则实现

在 website/src/errorsIdentifiers.json 中，function.duplicate标识符被映射到规则类：

• 规则类：PHPStan\Rules\Functions\DuplicateFunctionDeclarationRule
• 源码位置：src/Rules/Functions/DuplicateFunctionDeclarationRule.php#L67

从标识符与规则类的对应关系可以推断：该规则在 PHPStan 分析符号表（symbol table）时工作——当多个被分析文件（包括 stub 文件）各自携带同名函数的声明，导致符号表合并时发生冲突，规则即在冲突点报告function.duplicate错误。这类规则是 PHPStan 发现"无法执行或不符合开发者意图"代码的手段之一（该定位原则也体现在 website/errors/CLAUDE.md 的文档写作规范中）。

如何修复

方案一：删除重复声明，只保留一份

如果两份声明内容完全相同，直接删除其中一份，仅保留一个即可：

<?php declare(strict_types = 1); // file2.php namespace App; -function helper(): void -{ -}

方案二：两处声明本意不同，重命名其中一个

如果两处声明是有意保留的不同实现，则重命名其中一个函数，使二者名称不再冲突：

<?php declare(strict_types = 1); // file2.php namespace App; -function helper(): void +function helperAlternative(): void { }

重命名后，记得同步更新所有调用该函数的地方，避免引入"函数未定义"类的新问题。

方案三：检查 stub 文件配置

当错误确实来自 stub 文件时，除了删除/重命名重复声明，还应审视stubFiles配置（website/src/config-reference.md）：确认是否为同一函数编写了多个 stub，或 stub 中的函数签名与项目真实代码重复。保持 stub 文件与真实符号的唯一对应，是从根源上消除该错误的做法。

小结

function.duplicate是 PHPStan 在"静态发现运行时必然致命错误"方向上的典型规则：PHP 运行时会在脚本加载阶段直接因Cannot redeclare function终止，而 PHPStan 无需运行代码即可提前暴露这一隐患。修复思路归纳为三点：

1. 同名且同实现→ 删除重复声明，只保留一份；
2. 同名但有意保留多个实现→ 重命名其中一个函数；
3. 涉及 stub 文件→ 检查stubFiles配置，消除 stub 与项目代码之间的符号重复。

处理完重复声明后，重新运行 PHPStan 即可确认function.duplicate错误消失，且不会影响对项目中其余同名符号（类、接口、trait、枚举）的分析结果。

• 开发工具
• 代码质量
• 静态分析