本文详解如何通过 PHPStan 的泛型注解正确声明 Eloquent Builder 的模型类型，解决 query() 方法返回 Model|null 而非具体模型（如 Company|null）的类型推断错误，确保 Larastan 精准识别链式查询结果类型。
本文详解如何通过 phpstan 的泛型注解正确声明 eloquent builder 的模型类型，解决 `query()` 方法返回 `model|null` 而非具体模型（如 `company|null`）的类型推断错误，确保 larastan 精准识别链式查询结果类型。
在使用 Laravel + Larastan（PHPStan 的 Laravel 扩展）进行静态分析时，一个常见痛点是：当基类仓库（如 AbstractBaseRepository）通过泛型支持任意 Eloquent 模型时，query() 方法返回的 Builder 实例常被 PHPStan 误判为 Builder
根本原因在于：Illuminate\Database\Eloquent\Builder 本身是一个泛型类（自 Laravel 9.21+ 及对应版本的 Laravel Shift / Larastan 支持起），其完整签名是 Builder
✅ 正确做法是显式标注泛型返回类型：
<?php
namespace App\Repositories;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
/**
* @template TModel of Model
*/
abstract class AbstractBaseRepository
{
/** @var TModel */
protected $model;
/** @param TModel $model */
public function __construct(Model $model)
{
$this->model = $model;
}
/**
* @return Builder<TModel>
*/
public function query(): Builder
{
return $this->model->query();
}
}关键修改点：
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
- 在 query() 方法上方添加 PHPDoc 注解 @return Builder
； - 保持 Builder 类型引用不变（无需 use Illuminate\Database\Eloquent\Builder; 以外的改动）；
- 确保 TModel 已在类级别通过 @template 正确定义并约束为 Model 子类。
此时，CompanyRepository 继承该基类后，$this->query() 将被准确推断为 Builder
Method App\Repositories\CompanyRepository::firstByDomain() should return App\Models\Company|null but returns Illuminate\Database\Eloquent\Model|null.
⚠️ 注意事项：
- PHPStan 版本要求：需使用 PHPStan ≥ 1.10 且 Larastan ≥ 2.7（推荐 ≥ 3.0），以获得完整的泛型 Builder 支持；
- Laravel 版本兼容性：Builder 泛型自 Laravel 9.21 引入，若使用 Laravel 8.x，需配合 larastan/larastan 的兼容补丁或升级 Laravel；
- 不要依赖方法体推断：PHPStan 不解析方法内部实现（如 $this->model->query() 的实际返回类型），一切类型契约必须通过 PHPDoc 显式声明；
- 链式调用完整性：一旦 query() 类型正确，所有后续 Eloquent Builder 方法（where, orderBy, with, get, firstOrFail 等）均能获得精准泛型推导，无需额外注解。
通过这一简洁而关键的类型标注，您即可在不侵入业务逻辑的前提下，大幅提升 Laravel 项目的静态分析精度与开发体验——让类型系统真正成为您的协作者，而非障碍。
