企业官网建设流程全解析

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

本文围绕 PHPStan 错误标识parameter.notByRef展开，讲解它在 PHP 静态分析中的触发场景：当子类方法或接口实现把父级声明为「按引用传递」的参数改成了「按值传递」时，PHPStan 会报告该错误。读完本文你将掌握该错误的完整代码示例、背后的 Liskov 替换原则（LSP）依据、@param-out标签的关联触发路径，以及两种可直接落地的修复方案，并能从源码角度理解该规则由哪些 PHPStan 内部规则负责产出。

错误标识速览

在 PHPStan 的官方错误标识体系中，该错误定义于 website/errors/parameter.notByRef.md，其元信息为：

• title：parameter.notByRef
• shortDescription：Parameter is not passed by reference but the parent declares it as by-reference.（参数未按引用传递，但父级将其声明为按引用传递。）
• ignorable：true（该错误支持通过ignoreErrors配置忽略，详见下文）

这个标识与它的姊妹错误parameter.byRef（website/errors/parameter.byRef.md，子类把父级的按值参数改成了按引用传递）互为镜像，两者共同约束方法覆盖时的参数传递约定必须与父级一致。

触发该错误的代码示例

以下是最小复现示例（来自 website/errors/parameter.notByRef.md）：

<?php declare(strict_types = 1); interface Processor { public function process(string &$value): void; } class MyProcessor implements Processor { public function process(string $value): void { } }

接口Processor::process()声明了参数string &$value（按引用传递），而实现类MyProcessor::process()写成了string $value（按值传递）。PHPStan 在分析MyProcessor时会报告parameter.notByRef，提示实现方参数与接口的按引用约定不一致。

为什么会被报告：Liskov 替换原则与签名兼容性

根据 website/errors/parameter.notByRef.md 的说明，触发原因分两种情况：

1. 方法覆盖 / 接口实现：子类或实现类把某个参数声明为「不按引用传递」，但父类方法或接口把对应参数声明为「按引用传递」。这破坏了 Liskov 替换原则（LSP）——调用方如果基于父类/接口类型调用该方法，并预期参数会被修改，那么任何能在原地修改该参数的子类实现都无法被安全替换进去。
2. PHPDoc 的@param-out标签：当某个参数上使用了@param-out标签（表示该参数是“输出参数”，方法执行后会被写入新值），但该参数本身并没有按引用（&）传递时，也会触发本错误。@param-out的语义要求调用方能看到参数被修改后的值，而这只有通过引用传递才能成立。

从源码看规则归属

在 PHPStan 的规则注册表 website/src/errorsIdentifiers.json 中，parameter.notByRef由以下内部规则产出：

• PHPStan\Rules\Methods\OverridingMethodRule：负责检查方法覆盖/接口实现时参数签名的一致性，对应上面第 1 种情况；
• PHPStan\Rules\Methods\ConsistentConstructorRule：负责构造函数参数签名的一致性检查；
• PHPStan\Rules\PhpDoc\IncompatiblePhpDocTypeRule：负责 PHPDoc 类型与参数声明是否冲突的检查，对应上面第 2 种@param-out场景；
• PHPStan\Rules\PhpDoc\IncompatiblePropertyHookPhpDocTypeRule：面向 PHP 8.4 属性钩子（property hook）场景的同类 PHPDoc 检查。

可见该错误不仅发生在普通方法覆盖中，也覆盖构造函数与 PHPDoc 元数据层，是 PHPStan 对参数传递约定做“全链路”校验的体现。

如何修复

修复思路非常直接：让子类参数的传递方式与父级保持一致。将实现方法的参数补上&引用符即可（website/errors/parameter.notByRef.md）：

<?php declare(strict_types = 1); class MyProcessor implements Processor { - public function process(string $value): void + public function process(string &$value): void { } }

修复后，MyProcessor::process()与接口Processor::process()的参数传递约定完全一致，错误消除。

修复时的注意事项

• 不要反向修改接口：如果接口的方法语义就是“允许在方法内修改参数值”（比如参数兼具输入输出角色），正确做法是让实现方补&，而不是为了迁就实现而删除接口中的&，否则会破坏接口的契约语义。
• 警惕副作用：按引用传递意味着方法内部对参数的修改会反映到调用方的变量上。补上&之前，请确认方法体是否真的修改了该参数；如果方法体并不修改参数，则更合理的修复是修改接口/父类声明，去掉多余的&，让契约与实际行为一致。
• @param-out场景：如果错误来自@param-out标签，请为对应参数加上&；或者将@param-out改为@param（只读输入），前提是方法语义确实不再输出新值。@param-out要求参数按引用传递是语义层面的硬性要求，不能通过@param与@param-out混用来绕过。

反向情况的对照

若子类反向地把父级的按值参数改成了按引用参数（例如int $i写成int &$i），则会触发姊妹错误parameter.byRef，参见 website/errors/parameter.byRef.md 中的示例：

class Base { public function doFoo(int $i, int &$j): void { } } class Child extends Base { public function doFoo(int &$i, int $j): void // 错误：参数 #1 按引用传递， { // 但父类未按引用传递 } }

其修复方向同样是把参数传递方式对齐到父类。两个错误一正一反，共同保证「按引用/按值」约定在继承链上处处一致。

该错误能否被忽略

该错误的元数据中ignorable: true，意味着你可以在phpstan.neon的ignoreErrors中按标识精确忽略（例如针对历史遗留代码逐步治理时），语法如下：

parameters: ignoreErrors: - identifier: parameter.notByRef path: legacy/Module/*

不过需要提醒：忽略只是“暂时豁免”，parameter.notByRef反映的是真实的契约不一致问题，在 PHP 运行时层也可能引发致命错误（fatal error）。建议仅在明确知晓风险并计划后续修复时使用忽略机制，而不是长期依赖。

总结

parameter.notByRef是 PHPStan 在方法覆盖、接口实现、构造函数及 PHPDoc 层面统一校验参数传递约定的结果，其背后是 Liskov 替换原则对方法签名的严格要求。排查时先确认父级/接口的原始声明，再决定是给实现方补&、去掉父级多余的&，还是调整@param-out的使用；修复后保持子父两级参数传递方式完全一致即可。更完整的错误标识列表与规则归属可继续查阅 website/errors/parameter.notByRef.md 与 website/src/errorsIdentifiers.json。

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