PHPStan中真实类与存根类phpdoc类型组合的问题分析

问题背景

在使用PHPStan进行静态代码分析时，开发者遇到了真实类与存根类(stub)中phpdoc类型定义无法协同工作的问题。具体表现为当同时存在真实类和存根类定义时，真实类中的@phpstan-type和@phpstan-import-type注解会被忽略，导致自定义类型无法正常使用。

核心问题解析

存根类的设计初衷

PHPStan的存根文件(stub)机制主要用于以下场景：

1. 为第三方库或不可修改的代码提供类型信息补充
2. 覆盖现有代码的类型定义
3. 为魔术属性(magic properties)添加类型提示

当前限制

当同时存在真实类和存根类定义时：

1. 存根类中的phpdoc会完全覆盖真实类中的定义
2. 真实类中的自定义类型注解(@phpstan-type/@phpstan-import-type)会被忽略
3. 这种设计导致开发者无法在自有代码中使用存根类的同时保留自定义类型定义

解决方案探讨

官方推荐方案

1. 避免对自有代码使用存根文件
   对于可修改的代码，应直接在源文件中维护phpdoc，而不是使用存根文件。

2. 使用类反射扩展
   对于魔术属性的类型定义，可以开发PropertyClassReflectionExtension来动态声明属性类型。这种方式比维护存根文件更灵活且可维护。

3. 全局类型定义
   将自定义类型定义移至phpstan.neon配置文件中，作为全局类型使用。

技术实现细节

对于需要大量魔术属性的场景（如Eloquent模型），推荐实现自定义的反射扩展：

class ModelPropertyExtension implements PropertiesClassReflectionExtension
{
    public function hasProperty(ClassReflection $classReflection, string $propertyName): bool
    {
        return $classReflection->isSubclassOf(\Illuminate\Database\Eloquent\Model::class);
    }

    public function getProperty(ClassReflection $classReflection, string $propertyName): PropertyReflection
    {
        // 实现逻辑返回属性类型
    }
}

最佳实践建议

1. 自有代码
   直接在类文件中维护phpdoc，包括@property、@method等注解。

2. 第三方代码
   使用存根文件补充类型信息，但避免修改已有明确定义。

3. 魔术属性
   优先考虑反射扩展而非存根文件，特别是当属性定义需要复杂逻辑时。

4. 自定义类型
   对于项目广泛使用的类型，考虑在配置文件中定义为全局类型。

总结

PHPStan的设计哲学是存根文件主要用于不可修改的第三方代码。对于自有代码，直接在源文件中维护类型定义是更推荐的做法。当遇到需要大量魔术属性或复杂类型定义时，反射扩展机制提供了更强大和灵活的解决方案。理解这些设计原则和替代方案，可以帮助开发者更有效地利用PHPStan进行静态代码分析。