Larastan中whereRaw方法返回类型错误的深度解析

在使用Laravel ORM进行复杂查询时，我们经常会遇到需要直接使用原生SQL片段的场景。本文将以Larastan静态分析工具检测到的一个典型问题为例，深入探讨whereRaw方法在类型推断中的特殊表现及其解决方案。

问题现象

在Laravel的Eloquent查询构建器中，当我们在条件闭包内使用whereRaw方法时，Larastan可能会报告类型不匹配的错误。具体表现为：匿名函数被期望返回一个泛型模型构建器Builder<Model>，但实际返回的是具体模型构建器如Builder<JobAdvertisement>。

问题复现

考虑以下典型代码场景：

$subject = JobAdvertisement::query()
    ->where(fn (Builder $q) => $q
        ->when($request->str('radius'), function (Builder $q, Stringable $radius) use ($request) {
            ['longitude' => $lng, 'latitude' => $lat] = $request->only('longitude', 'latitude');
            $q->whereRaw("ST_Distance_Sphere(ST_GeomFromText('POINT($lng $lat)'), location_point) <= ?", [$radius->toString()]);
        })
    );

这段代码在执行地理空间查询时，Larastan会抛出类型错误，提示返回类型不符合预期。

问题根源

1. 泛型类型协变问题：Eloquent的Builder使用了泛型类型参数，但PHPStan检测到这些参数不是协变的

2. 类型推断中断：当显式声明Builder类型时，会覆盖Laravel的自动类型推断机制，导致泛型信息丢失

3. 闭包返回要求：when方法的回调函数理论上不需要返回值，但类型系统仍会检查返回类型

解决方案

方案一：移除显式类型声明

最简单的解决方案是移除闭包参数的类型声明，让Laravel自动推断类型：

$subject = JobAdvertisement::query()
    ->where(fn ($q) => $q
        ->when($request->str('radius'), function ($q, Stringable $radius) use ($request) {
            // 实现代码不变
        })
    );

方案二：使用类型注释

如果需要保留类型安全，可以使用PHPDoc注释来明确类型：

$subject = JobAdvertisement::query()
    ->where(fn (/** @var Builder<Model> $q */ $q) => $q
        ->when($request->str('radius'), function (/** @var Builder<Model> */ $q, Stringable $radius) use ($request) {
            // 实现代码不变
            return $q;
        })
    );

最佳实践建议

1. 权衡类型安全与便利性：在简单查询中可以依赖自动推断，复杂查询则建议使用类型注释

2. 保持一致性：项目中应统一采用一种风格，要么全部显式类型，要么全部依赖推断

3. 关注更新：这个问题在PHPStan新版本中可能已经修复，及时升级工具链

4. 理解底层机制：深入理解Laravel查询构建器的泛型实现原理，有助于编写更健壮的代码

总结

Larastan检测到的这个类型问题反映了静态分析与动态语言特性之间的张力。通过理解Eloquent构建器的泛型工作机制，开发者可以更灵活地处理这类类型系统边界情况。在实际开发中，应根据项目规范和个人偏好选择最适合的解决方案，同时保持对工具链更新的关注，以确保代码质量和开发效率的最佳平衡。