解决 Laravel Query Builder 在 PHPStan 中的类型推断问题

在使用 Laravel 开发过程中，Spatie 的 laravel-query-builder 是一个非常流行的扩展包，它提供了优雅的 API 来构建复杂的数据库查询。然而，当结合静态分析工具 PHPStan 使用时，开发者可能会遇到类型推断不准确的问题。

问题背景

当开发者使用 QueryBuilder 构建查询并获取结果时，PHPStan 无法正确推断返回值的具体类型。例如，当查询一个特定模型时，期望返回的是该模型的集合，但 PHPStan 却只能推断出通用的 Illuminate\Database\Eloquent\Collection 类型，丢失了模型的具体类型信息。

原因分析

这个问题主要源于 PHPStan 无法自动识别 QueryBuilder 的泛型特性。虽然 Laravel 的 Eloquent Builder 已经支持了泛型标注，但 Spatie 的 QueryBuilder 包装了原生 Builder 后，类型信息在传递过程中丢失了。

解决方案

要解决这个问题，我们需要为 QueryBuilder 创建类型存根（stub）文件，明确声明其泛型行为。以下是完整的解决方案：

1. 创建 QueryBuilder 类型存根

在项目中创建 stubs/phpstan/QueryBuilder.stub 文件，内容如下：

<?php

namespace Spatie\QueryBuilder;

use Illuminate\Database\Eloquent\Builder as EloquentBuilder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\Relation;
use Illuminate\Http\Request;

/**
 * @template TModel of Model
 *
 * @mixin EloquentBuilder<TModel>
 */
class QueryBuilder
{
    /**
     * @var EloquentBuilder<TModel>|Relation<TModel, Model, mixed>
     */
    protected EloquentBuilder|Relation $subject;

    /**
     * @param  EloquentBuilder<TModel>|Relation<TModel, Model, mixed>  $subject
     */
    public function __construct(
        EloquentBuilder|Relation $subject,
        ?Request $request = null
    ) {}

    /**
     * @template T of Model
     *
     * @param  EloquentBuilder<T>|Relation<T, Model, mixed>|string  $subject
     * @return self<T>
     */
    public static function for(
        EloquentBuilder|Relation|string $subject,
        ?Request $request = null
    ): self {}

    /**
     * @param  string  $name
     * @param  mixed  $arguments
     * @return EloquentBuilder<TModel>|self<TModel>
     */
    public function __call($name, $arguments): EloquentBuilder {}

    /**
     * @return EloquentBuilder<TModel>
     */
    public function getEloquentBuilder(): EloquentBuilder {}

    /**
     * @return Relation<TModel, Model, mixed>|EloquentBuilder<TModel>
     */
    public function getSubject(): Relation|EloquentBuilder {}
}

2. 创建辅助 Trait 简化使用

为了更方便地在项目中使用类型安全的 QueryBuilder，可以创建一个 Trait：

<?php

namespace App\Traits;

use Illuminate\Database\Eloquent\Builder;
use Spatie\QueryBuilder\QueryBuilder;

trait CreatesSpatieQueryBuilder
{
    /**
     * @template T of \Illuminate\Database\Eloquent\Model
     *
     * @param  class-string<T>|Builder<T>  $query
     * @return QueryBuilder<T>
     */
    private function getQueryBuilder(string|Builder $query): QueryBuilder
    {
        return QueryBuilder::for($query);
    }
}

实现原理

1. 泛型模板定义：通过 @template TModel of Model 声明 QueryBuilder 是一个泛型类，其类型参数 TModel 必须是 Model 的子类。

2. 类型参数传递：在静态方法 for() 中，使用新的模板参数 T 来捕获输入 Builder 的具体模型类型，并确保返回的 QueryBuilder 实例具有相同的类型参数。

3. 方法代理：通过 @mixin 标注和 __call 方法的类型声明，确保所有 Builder 方法的调用都能正确传递类型信息。

使用效果

应用这些修改后，PHPStan 将能够正确识别 QueryBuilder 返回的集合中包含的具体模型类型，大大提高了静态分析的准确性，同时为开发者提供了更好的代码提示和类型检查。

最佳实践

1. 始终为模型类添加正确的 @method 标注，如 @method static Builder<FormField>|FormField query()

2. 在复杂查询场景中，考虑将查询逻辑封装到专门的查询类中，并使用类型存根确保类型安全

3. 定期更新 PHPStan 和 Larastan 版本，以获取更好的类型推断支持

通过这种方式，开发者可以在享受 Spatie QueryBuilder 便利性的同时，不牺牲代码的静态分析质量，实现更好的开发体验和更可靠的代码质量。