PHPStan 类型提示进阶：如何安全地将属性声明为比接口更具体的类

当 phpstan 检测到属性类型声明（如 `@var specificrepository`）与初始化表达式返回类型（如 `repositoryinterface`）不兼容时，会报错；正确做法是用接口声明属性，并通过带运行时校验的 getter 提供具体类型保障。

在 PHP 静态分析（尤其是 PHPStan Level 3+）中，类型安全性要求严格：属性的声明类型必须能被静态推导所保证。即使你确信 ORM::getRepository(Something::class) 在运行时总会返回 SpecificRepository 实例，PHPStan 仍只信任方法签名——而该方法声明返回的是 RepositoryInterface。因此，直接使用 /** @var SpecificRepository */ 注解会导致类型不兼容错误：

// ❌ 错误：违反静态类型契约
/** @var SpecificRepository */
protected $repository;

public function __construct(ORM $orm)
{
    $this->repository = $orm->getRepository(Something::class); // 返回 RepositoryInterface → 不兼容 SpecificRepository
}

✅ 正确方案是「接口优先 + 安全降级」：

1. 属性声明为通用接口，确保静态分析通过；
2. 提供受保护的 getter 方法，在运行时显式校验并断言具体类型；
3. 在业务逻辑中统一调用 getter，兼顾 IDE 补全、PHPStan 通过与运行时安全。

class Something
{
    protected RepositoryInterface $repository;

    public function __construct(ORM $orm)
    {
        $this->repository = $orm->getRepository(Something::class);
    }

    protected function getSpecificRepository(): SpecificRepository
    {
        if (!$this->
repository instanceof SpecificRepository) {
            throw new RuntimeException(
                sprintf('Expected SpecificRepository, got %s', get_class($this->repository))
            );
        }
        return $this->repository;
    }

    public function doSomething(): void
    {
        // ✅ IDE 可补全 SpecificRepository 方法，PHPStan 接受 SpecificRepository 类型
        $this->getSpecificRepository()->customMethod(); // 如 findActive()
    }
}

? 额外优化建议：

• 若项目已启用 PHP 8.0+，可改用属性类型声明（protected RepositoryInterface $repository;）替代 PHPDoc，更现代且语义清晰；
• 对高频使用的具体仓库，可封装为 SpecificRepositoryAwareTrait，复用校验逻辑；
• 在测试中覆盖 getSpecificRepository() 的异常分支，确保类型校验生效；
• 若确定所有 getRepository() 调用均可被精准推导（如通过 PHPStan 扩展），可考虑编写自定义 PHPStan 扩展 来增强返回类型推断——但这属于高级定制，常规项目推荐上述 getter 方案。

该模式平衡了静态分析严谨性、IDE 开发体验与运行时健壮性，是 PHP 生态中处理“动态具体化类型”的最佳实践之一。