17370845950

PHP魔术方法注释必须写在声明上方且参数名须符合约定：__get/__set参数名分别为$name/$value，__invoke需标注callable类型，__destruct应说明副作用与执行不确定性。

PHP魔术方法注释必须写在声明上方，不能写在函数体内

PHP的魔术方法（如 __construct、__get、__toString）本身不支持返回类型声明（PHP 8.0+ 也不允许对它们加 void 或其他返回类型），所以文档注释（PHPDoc）是唯一能明确表达意图和参数含义的方式。如果把注释写在方法体内部，PHPDoc 解析器（比如 PHPStan、IDE）会完全忽略它。

• ✅ 正确位置：紧贴 function 关键字前一行，且中间无空行
• ❌ 错误写法：

  public function __toString()
  {
      /** @return string */  // IDE 看不见，静态分析不识别
      return (string) $this->id;
  }

• PHPDoc 中建议包含 @param、@return、@throws（如有异常逻辑）

__get 和 __set 的参数名必须写成 $name，否则 PHPDoc 失效

虽然 PHP 允许你把 __get 的参数起名叫 $key 或 $prop，但主流工具链（PhpStorm、PHPStan、Psalm）都依赖「约定参数名」来推断魔术行为。一旦改名，IDE 就无法正确补全属性访问、也无法识别动态属性的类型。

• ✅ 推荐写法：

  /**
   * @param string $name 属性名（区分大小写）
   * @return mixed
   */
  public function __get(string $name)

• ❌ 危险写法：

  public function __get(string $prop) { ... }

  —— 此时 $obj->foo 在 IDE 中不会触发 __get 的类型提示
• __set 同理，第二个参数必须叫 $value，否则类型推导断裂

__invoke 注释要标注 calla

ble 类型，避免与普通方法混淆

__invoke 让对象可被当作函数调用，但它本质上仍是方法。如果不加明确注释，静态分析可能误判为“未使用的方法”，或在类型检查中丢失 callable 上下文。

• 必须标注 @return 和输入参数，例如：

  /**
   * @param int $x
   * @param string $y
   * @return array
   */
  public function __invoke(int $x, string $y): array

• 若该类常用于回调（如事件处理器），建议额外加 @implements \Closure 或 @psalm-callable（Psalm 场景）
• 注意：PHP 8.0+ 支持 __invoke(): void，但 PHPDoc 仍应写 @return void 以兼容旧工具

__destruct 不需要 @return，但必须注明副作用和资源释放逻辑

__destruct 没有返回值，写 @return void 是冗余的；更重要的是，它执行时机不确定（可能在脚本结束前任意时刻），容易引发资源竞争或已销毁对象访问。注释里得把“做了什么”和“不能做什么”说清。

• ✅ 实用注释示例：

  /**
   * 清理临时文件并关闭数据库连接。
   * 注意：不保证在所有异常退出路径中都被调用；
   * 若需确定性释放，请显式调用 close()。
   */
  public function __destruct()

• 不要在 __destruct 中 throw 异常 —— PHP 会静默吞掉，且可能中断垃圾回收
• 避免在其中调用 $this->otherMethod()，因为其他属性可能已被析构

实际项目里，最常被忽略的是 get/set 的参数命名约束和 __destruct 的执行不确定性——这两点不靠注释说清楚，后期 debug 成本远高于写几行说明。