Larastan 中 Model::newCollection() 方法类型检查问题的解决方案

在 Laravel 项目中，我们经常会为模型创建自定义集合类来扩展功能。然而，在使用 Larastan 进行静态分析时，开发者可能会遇到关于 newCollection() 方法返回类型兼容性的问题。

问题背景

当开发者尝试在 Laravel 模型中实现 newCollection() 方法时，通常会遇到两种类型检查错误：

1. 返回类型不兼容错误，提示自定义集合类与基础 Collection 类不匹配
2. 泛型类型参数约束问题，特别是关于 TModel 类型的限制

解决方案详解

基础解决方案

对于不打算被继承的模型类，最简单的解决方案是将模型类声明为 final：

final class Post extends Model
{
    /** @use HasCollection<PostCollection> */
    use HasCollection;

    protected static string $collectionClass = PostCollection::class;
}

/** @extends Collection<array-key, Post> */
final class PostCollection extends Collection
{
    public function foo(): self
    {
        return $this->where('title', 'Foo');
    }
}

这种方法简洁明了，适用于大多数不需要继承的场景。

高级解决方案

对于需要支持继承的模型类，需要使用更复杂的类型注解：

class Post extends Model
{
    /** @use HasCollection<PostCollection<int, static>> */
    use HasCollection;

    protected static string $collectionClass = PostCollection::class;
}

/**
 * @template TKey of array-key
 * @template TModel of Post
 * @extends Collection<TKey, TModel>
 */
class PostCollection extends Collection
{
    /** @return static<TKey, TModel> */
    public function foo(): static
    {
        return $this->where('title', 'Foo');
    }
}

关键点说明：

1. 使用 static 关键字确保子类也能正确返回自己的集合类型
2. 严格定义泛型参数约束，确保类型安全
3. 方法返回类型使用 static 而非 self，以保持协变性

技术要点解析

1. 泛型参数约束：在集合类中，TModel 应该约束为具体的模型类或其父类，如 @template TModel of Post

2. 静态返回类型：在可能被继承的类中，使用 static 而非 self 可以确保子类方法返回正确的类型

3. 协变与逆变：理解集合类方法返回类型需要协变，而参数类型需要逆变，这对正确注解至关重要

4. Laravel 的 HasCollection 特性：Laravel 11 引入的这个特性简化了自定义集合的集成，但需要正确的泛型注解才能与静态分析工具配合工作

最佳实践建议

1. 优先考虑将模型类声明为 final，除非确实需要继承
2. 对于简单项目，可以使用 Laravel 的 HasCollection 特性简化实现
3. 在复杂场景下，手动实现 newCollection() 方法并提供完整类型注解
4. 保持集合类方法的返回类型与 Laravel 基础集合类一致，避免类型不匹配

通过理解这些概念和解决方案，开发者可以更好地在 Laravel 项目中实现类型安全的自定义集合类，同时保持与 Larastan 静态分析工具的兼容性。