Larastan 中自定义 Eloquent 集合的类型推断问题解析

在 Laravel 开发中，Eloquent 模型允许开发者通过重写 newCollection() 方法来返回自定义集合类。然而，当使用 Larastan 进行静态分析时，这种自定义集合的类型推断可能会遇到一些问题。本文将深入探讨这一现象及其解决方案。

问题现象

当开发者创建自定义集合类并继承自 Illuminate\Database\Eloquent\Collection 时，Larastan 在分析过程中可能会出现以下两种典型情况：

1. 集合类型正确但元素类型丢失
   虽然能正确识别自定义集合类，但无法推断集合中元素的类型，导致无法访问模型特有的属性。

2. 元素类型正确但集合类型丢失
   能正确推断集合中元素的类型，但无法识别自定义集合类，默认返回基础 Eloquent 集合类型。

根本原因

这个问题源于 PHPStan 的静态分析机制与 Laravel 动态特性的结合处。PHPStan 主要通过类型提示和 PHPDoc 注释来分析代码，而 Laravel 的集合系统高度依赖运行时行为。

完整解决方案

1. 正确定义自定义集合类

自定义集合类需要完整定义泛型信息：

/**
 * @template TKey of array-key
 * @template TModel of \App\Base\Model
 * @extends \Illuminate\Database\Eloquent\Collection<TKey, TModel>
 */
class ModelCollection extends \Illuminate\Database\Eloquent\Collection
{
    // 集合实现
}

2. 完善模型的 newCollection 方法

在模型中，newCollection 方法需要完整的类型提示和 PHPDoc：

/**
 * @param array<int, static> $models
 * @return ModelCollection<int, static>
 */
public function newCollection(array $models = []): ModelCollection
{
    return new ModelCollection($models);
}

3. 使用 Trait 实现更灵活的方案

为了更好的代码组织和复用性，建议使用 Trait 来实现自定义集合功能：

/**
 * @template TCollection of \Illuminate\Database\Eloquent\Collection
 * @mixin \Illuminate\Database\Eloquent\Model
 */
trait HasCustomCollection
{
    protected static string $collectionClass;
    
    /**
     * @param array<int, static> $models
     * @return TCollection
     */
    public function newCollection(array $models = []): \Illuminate\Database\Eloquent\Collection
    {
        return new static::$collectionClass($models);
    }
}

在模型中使用：

/**
 * @property string $name
 */
class User extends Model
{
    /** @use HasCustomCollection<\App\Collections\UserCollection> */
    use HasCustomCollection;
    
    protected static string $collectionClass = \App\Collections\UserCollection::class;
}

常见场景处理

1. 查询结果类型推断

对于自定义查询方法，需要显式声明返回类型：

/**
 * @return \Illuminate\Database\Eloquent\Builder<self>
 */
public static function activeUsers(): \Illuminate\Database\Eloquent\Builder
{
    return static::query()->where('active', true);
}

2. 集合转换操作

当对集合进行 map、filter 等操作时，建议省略闭包参数类型以保持泛型信息：

// 推荐写法
$names = $users->map(fn($user) => $user->name);

// 不推荐写法（可能导致泛型信息丢失）
$names = $users->map(fn(User $user) => $user->name);

最佳实践建议

1. 始终为自定义集合类定义完整的泛型信息
2. 为所有返回集合或构建器的方法添加 PHPDoc 注释
3. 避免在闭包参数中重复类型声明
4. 考虑使用 Trait 来实现集合自定义功能
5. 定期清理调试用的 dumpType 调用

通过遵循这些实践，可以确保 Larastan 能够正确推断自定义集合的类型信息，从而提供更准确的静态分析结果。