能否通过PHPdoc从类变量定义PHP方法的参数类型？

问题描述 #

现有代码：

class UserProvider
{
    protected string $className = User::class;

    /**
     * @param User $entity
     */
    public function getData($entity): array
    {
        $data['name'] = $entity->getName();

        return $data;
    }
}

希望实现通过类属性动态指定参数类型的写法：

class UserProvider
{
    protected string $className = User::class;

    /**
     * @param [UserProvider->className] $entity
     */
    public function getData($entity): array
    {
        $data['name'] = $entity->getName();

        return $data;
    }
}

询问是否有可行的实现思路。

可行实现思路 #

1. 利用PHP 8.1+泛型特性（推荐） #

如果项目使用PHP 8.1及以上版本，泛型是最原生的解决方案，能让类型系统直接识别，无需依赖自定义注释解析：

class EntityProvider<T>
{
    public function getData(T $entity): array
    {
        return [
            'name' => $entity->getName()
        ];
    }
}

// 使用时指定具体类型
class UserProvider extends EntityProvider<User> {}

这样UserProvider中的getData方法参数会被PHPStan、Psalm等静态分析工具识别为User类型，完全替代你想要的动态注释效果。

2. 自定义注释解析+静态分析工具扩展 #

如果必须保留原有的类属性写法，可以通过以下步骤实现：

• 定义自定义PHPDoc标签（比如@paramFromProperty className）替代[UserProvider->className]
• 编写PHPStan/Psalm的自定义规则扩展，让工具解析这个标签时，读取当前类的className属性值作为参数类型
• 示例注释写法：

  /**
   * @paramFromProperty className $entity
   */
  public function getData($entity): array
  

3. 代码生成工具预编译注释 #

使用PHP Parser等代码生成器，在项目构建阶段自动将类属性中的类名替换到PHPDoc注释里：

• 编写脚本扫描所有类似UserProvider的类
• 读取$className属性的值，替换对应方法的@param注释内容
• 生成最终带硬编码类型注释的代码文件，供开发和静态分析使用

4. 使用注解（Attribute）配合运行时类型检查 #

如果需要运行时的类型验证，可以结合PHP 8.0+的注解特性：

#[\Attribute]
class ParamFromProperty
{
    public function __construct(public string $propertyName) {}
}

class UserProvider
{
    protected string $className = User::class;

    /**
     * @param mixed $entity
     */
    #[ParamFromProperty('className')]
    public function getData($entity): array
    {
        // 运行时验证类型
        $expectedClass = $this->className;
        if (!$entity instanceof $expectedClass) {
            throw new \TypeError(sprintf('Expected instance of %s, got %s', $expectedClass, get_debug_type($entity)));
        }

        return [
            'name' => $entity->getName()
        ];
    }
}

这种方式能在运行时保证类型正确，但静态分析工具无法直接识别，需要配合扩展才能实现IDE提示。

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