PHP怎么注释引用传参_PHP引用传参注释【区分】

PHP中函数参数前加&表示引用传参，是强制语法；@param &$var等PHPDoc仅为说明约定，不改变执行逻辑，二者必须同步维护。

PHP函数参数前加&符号表示引用传参

PHP中，&$var 是明确的引用传递语法，不是注释，也不是可选标记——它直接改变参数传递行为。所谓“注释引用传参”，其实是开发者用注释说明「这个参数会被修改」或「预期以引用方式调用」，但PHP本身不识别这类注释，也不会据此改变执行逻辑。

@param &$var 的PHPDoc是行业约定，非PHP执行依据

在函数文档块中写 @param int &$count，只是告诉阅读代码的人：该参数预期被函数内部修改，调用方应传入变量（而非字面量），且需注意副作用。PHP解释器完全忽略它。

• 错误写法：

  function increment($count) { $count++; } // 没加& → 值传递，原变量不变

• 正确引用写法：

  function increment(&$count) { $count++; }

• 配套PHPDoc建议：

  /**
   * @param int &$count 被原地递增的计数器（引用传参）
   */

• 调用时若传字面量会报错：increment(5); → Fatal error: Only variables can be passed by reference

引用传参和值传参的运行时差异必须靠&显式声明

PHP不会根据注释、变量名或PHPDoc自动切换传参方式。是否引用，只取决于函数定义时是否在参数前写了 &。漏写 & 却在注释里写 @param &$x，会导致调用方误以为能修改原变量，实际却毫无效果。

• 值传递（默认）：function foo($a) { $a = 10; } → 外部变量不受影响
• 引用传递（显式）：function foo(&$a) { $a = 10; } → 外部变量被修改
• PHP 7.4+ 支持类型声明与引用共存：function bar(int &$x): void，但 & 仍不可省略
• 数组元素、对象属性不能直接加 & 传参：foo(&$arr[0]) 合法，但 foo(&$obj->prop) 在 PHP 8.1+ 已废弃，会触发 Deprecated 警告

IDE和静态分析工具依赖PHPDoc推断引用意图

虽然PHP不执行注释，但PhpStorm、PHPStan、Psalm 等工具会读取 @param &$var 来做类型检查和警告提示。比如你写了 @param array &$data 却在函数里没修改 $data，某些配置下会提示「未使用引用」；反之，若函数内修改了参数但没写 & 和对应PHPDoc，IDE可能标黄并提示「可能遗漏引用声明」。

• 真实风险点：多人协作时，有人只改了PHPDoc没加 &，或只加 & 没更新注释，导致语义和实现脱节
• 对象本身是引用语义（PHP 5.0+），但这是对象标识符的复制，不是传

  

  统引用传参，@param MyClass $obj 不需要写 &，除非你真要替换整个对象实例（如 $obj = new MyClass();）
• 函数返回引用（function &getRef() { return $var; }）和参数引用是两回事，别混淆

引用传参的「声明」和「说明」必须同步维护——& 是执行层强制要求，@param &$x 是协作层必要补充，缺一不可。最常出问题的地方，恰恰是改了其中一个，忘了另一个。