如何通过PhpDoc自动标记类的魔术调用行为以简化代码？

我们用魔术行为给类添加额外功能，但现在每个带这种特性的类都得重复写对应行为类的所有公共方法注释，重复代码太多了，比如下面这段：

/**
 * @see \App\Behaviour::someMethod
 * @method mixed someMethod(string ...$params)
 *
 * @see \App\Behaviour::anotherMethod
 * @method void anotherMethod()
 */
class Foo {
    public function __call(string $method, array $params) {
        $this->behaviour->{$method}(...$params);
    }
}

有没有办法自动标记这种魔术行为，不用每个类都重复写这些方法注释？比如像下面这种设想的语法：

/**
 * @magic-call \App\Behaviour
 */
class Foo {

}

可行的解决方案 #

1. 用IDE自定义元数据（以PhpStorm为例）

PhpStorm支持通过.phpstorm.meta.php文件配置魔术方法的映射，让IDE自动识别行为类的方法，不用手动写注释。

创建项目根目录的.phpstorm.meta.php文件，内容如下：

<?php
namespace PHPSTORM_META {
    // 针对Foo类的__call方法，映射到App\Behaviour的所有方法
    override(\Foo::__call(0), map([
        '' => '@\\App\\Behaviour::*'
    ]));
    
    // 如果有多个类需要配置，可以批量处理
    override(\Bar::__call(0), map([
        '' => '@\\App\\AnotherBehaviour::*'
    ]));
}

这样IDE就能像识别普通方法一样，提示行为类里的方法，还能做类型检查。

2. 用代码生成工具自动生成注释

自己写个简单的脚本或者用注解处理器，扫描带有自定义注解的类，自动生成对应的@method注释。

首先定义一个注解类：

<?php
/**
 * @Annotation
 * @Target("CLASS")
 */
class MagicCall {
    // 要关联的行为类
    public $class;
}

然后给目标类加注解：

/**
 * @MagicCall(class="\App\Behaviour")
 */
class Foo {
    public function __call(string $method, array $params) {
        $this->behaviour->{$method}(...$params);
    }
}

接下来写脚本，用反射读取类的注解，获取行为类的所有公共方法，然后自动生成注释块替换到类文件里。脚本逻辑大概是：

• 扫描指定目录下的PHP文件
• 对每个带@MagicCall注解的类，反射获取目标行为类的公共方法
• 生成对应的@see和@method注释
• 将生成的注释写入原类文件的注释块中

3. 用Trait替代魔术方法（静态场景）

如果行为类的方法是固定的，不需要动态切换，直接用Trait把行为类的方法引入目标类，这样IDE天然支持方法提示，完全不用写魔术方法和注释：

trait BehaviourTrait {
    public function someMethod(string ...$params) {
        // 这里实现方法逻辑，或者委托给行为实例
        return $this->behaviour->someMethod(...$params);
    }
    
    public function anotherMethod() {
        $this->behaviour->anotherMethod();
    }
}

class Foo {
    use BehaviourTrait;
    
    private $behaviour;
    
    public function __construct(\App\Behaviour $behaviour) {
        $this->behaviour = $behaviour;
    }
}

这种方式更直观，IDE支持也更好，适合不需要动态切换行为的场景。

内容的提问来源于stack exchange，提问作者Justinas