Laravel模型自定义集合？集合类如何自定义？-Laravel-PHP中文网

Laravel允许为模型自定义集合类，通过继承Illuminate\Database\Eloquent\Collection并重写模型的newCollection方法，可将业务逻辑如getTotalSales、publishedItems等封装至集合中，提升代码复用性与可维护性，使集合具备特定行为，如订单汇总、文章标签筛选等，同时需注意预加载关联数据以避免N+1查询问题。

laravel模型自定义集合？集合类如何自定义？

是的，Laravel允许你为模型指定自定义的集合类，这在处理特定业务逻辑或为一组模型实例提供定制化操作时非常有用。核心思路是重写模型中的一个方法，并创建你自己的集合类，以便将与该模型集合相关的逻辑封装起来。

解决方案

要为Laravel模型自定义集合，主要涉及两个步骤：首先是创建你自己的集合类，然后是在模型中告诉Laravel使用这个自定义集合。

首先，你需要创建一个继承自

Illuminate\Database\Eloquent\Collection

登录后复制

的自定义集合类。这个类通常放在

app/Collections

登录后复制

或

app/Models/Collections

登录后复制

这样的目录中，保持项目结构清晰。在这个类里，你可以添加任何你需要的辅助方法或业务逻辑。

// app/Collections/MyCustomCollection.php
<?php

namespace App\Collections;

use Illuminate\Database\Eloquent\Collection;

class MyCustomCollection extends Collection
{
    /**
     * 获取集合中所有商品的销售总额。
     * 假设集合中的每个模型都有一个 'price' 属性。
     *
     * @return float
     */
    public function getTotalSales(): float
    {
        return $this->sum('price');
    }

    /**
     * 过滤出所有已发布的商品。
     * 假设集合中的每个模型都有一个 'is_published' 属性。
     *
     * @return static
     */
    public function publishedItems(): static
    {
        return $this->filter(fn ($item) => $item->is_published);
    }
}

登录后复制

接下来，你需要在你的 Eloquent 模型中重写

newCollection

登录后复制

方法，让它返回你的自定义集合实例。

// app/Models/Product.php
<?php

namespace App\Models;

use App\Collections\MyCustomCollection; // 引入你的自定义集合类
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Collection; // 引入基础集合类，尽管不直接使用，但明确其父类

class Product extends Model
{
    // ... 其他模型定义

    /**
     * 创建一个新的 Eloquent 集合实例。
     *
     * @param  array  $models
     * @return \Illuminate\Database\Eloquent\Collection
     */
    public function newCollection(array $models = []): Collection
    {
        return new MyCustomCollection($models);
    }
}

登录后复制

现在，当你从

Product

登录后复制

模型中获取多个实例时（例如

Product::all()

登录后复制

或

Product::where(...)->get()

登录后复制

），返回的将不再是标准的

Illuminate\Database\Eloquent\Collection

登录后复制

实例，而是你的

MyCustomCollection

登录后复制

实例，你就可以直接调用上面定义的

getTotalSales()

登录后复制

或

publishedItems()

登录后复制

等方法了。

// 示例用法
$products = Product::all(); // $products 现在是 MyCustomCollection 的实例

$totalSales = $products->getTotalSales();
$publishedProducts = $products->publishedItems();

登录后复制

为什么我们需要为Laravel模型定义专属集合？

这其实是个很有意思的问题，我个人觉得，它更多地体现了面向对象设计中“封装”和“单一职责”的原则。在我看来，为Laravel模型定义专属集合，不仅仅是为了炫技或者仅仅多写几行代码，它背后有着非常实际的业务驱动和代码质量考量。

想象一下，你有一个

Order

登录后复制

模型，每次获取到一系列订单时，你可能需要计算它们的总金额、筛选出已支付的订单、或者生成一份简单的报表。如果这些逻辑都散落在控制器、服务层甚至视图层，那么代码会变得非常冗余且难以维护。你可能会看到这样的代码片段：

// 在控制器或服务中
$orders = Order::where('user_id', auth()->id())->get();
$totalAmount = $orders->sum('amount');
$paidOrders = $orders->filter(fn($order) => $order->status === 'paid');

登录后复制

这段代码本身没错，但如果这样的逻辑在多个地方重复出现，或者每次都需要进行更复杂的计算，比如考虑折扣、运费等，那么自定义集合的价值就凸显出来了。

通过自定义

OrderCollection

登录后复制

，你可以把所有与“一组订单”相关的业务逻辑都封装进去，比如：

// 在 OrderCollection 中
public function getTotalAmount(): float
{
    // 这里可以包含复杂的折扣、运费计算逻辑
    return $this->sum('amount_after_discount');
}

public function getPaidOrders(): static
{
    return $this->filter(fn($order) => $order->status === 'paid');
}

public function generateSummaryReport(): array
{
    // 生成一份订单摘要报告
    return [
        'total' => $this->count(),
        'paid' => $this->getPaidOrders()->count(),
        'unpaid' => $this->filter(fn($order) => $order->status === 'pending')->count(),
        'total_revenue' => $this->getTotalAmount(),
    ];
}

登录后复制

这样一来，你的控制器或服务层代码就变得异常简洁和富有表达力：

$userOrders = Order::where('user_id', auth()->id())->get(); // 返回 OrderCollection 实例
$report = $userOrders->generateSummaryReport();
$paidOrders = $userOrders->getPaidOrders();

登录后复制

这不仅提高了代码的可读性，更重要的是，它将业务逻辑从使用层剥离出来，集中管理。当业务规则发生变化时，你只需要修改集合类中的方法，而不需要去寻找散落在各处的代码。这在我看来，就是自定义集合最大的魅力所在——它让你的代码更“智能”，更“有组织”，也更“好维护”。它让集合不再仅仅是数据的容器，而是具备了特定行为和智慧的业务实体。

如何创建并使用一个自定义的Laravel集合类？

创建和使用自定义Laravel集合类，在我看来，是提升项目代码质量和可维护性的一个重要实践。它允许你将与特定模型集合相关的业务逻辑和辅助方法集中管理，避免代码冗余。

让我们以一个更具体的例子来演示这个过程。假设我们正在构建一个博客系统，有一个

Post

登录后复制

模型。我们经常需要获取已发布的文章、计算文章的阅读时长总和，或者筛选出包含特定标签的文章。这些操作如果每次都写一遍，会非常重复。

步骤 1：定义你的自定义集合类

首先，我们创建一个名为

PostCollection

登录后复制

的类。通常，我会把这类文件放在

app/Collections

登录后复制

目录下，这样组织起来比较清晰。

// app/Collections/PostCollection.php
<?php

namespace App\Collections;

use Illuminate\Database\Eloquent\Collection;

class PostCollection extends Collection
{
    /**
     * 过滤出所有已发布的文章。
     * 假设 Post 模型有一个 'is_published' 字段。
     *
     * @return static
     */
    public function published(): static
    {
        return $this->filter(fn ($post) => $post->is_published);
    }

    /**
     * 计算所有文章的阅读时长总和。
     * 假设 Post 模型有一个 'read_time_minutes' 字段。
     *
     * @return int
     */
    public function totalReadTime(): int
    {
        return $this->sum('read_time_minutes');
    }

    /**
     * 过滤出包含特定标签的文章。
     * 假设 Post 模型有一个 'tags' 关联关系，返回一个标签集合。
     *
     * @param string $tag
     * @return static
     */
    public function withTag(string $tag): static
    {
        return $this->filter(fn ($post) =>
            $post->tags->contains('name', $tag) // 假设标签模型有 'name' 字段
        );
    }
}

登录后复制

这里我们定义了三个自定义方法：

published()

登录后复制

、

totalReadTime()

登录后复制

和

withTag()

登录后复制

。它们分别处理了文章集合的常见需求。

步骤 2：在 Eloquent 模型中关联自定义集合

百灵大模型

蚂蚁集团自研的多模态AI大模型系列

177

查看详情

接下来，我们需要告诉

Post

登录后复制

模型，当它返回多个实例时，应该使用

PostCollection

登录后复制

而不是默认的

Illuminate\Database\Eloquent\Collection

登录后复制

。这通过重写模型中的

newCollection

登录后复制

方法来实现。

// app/Models/Post.php
<?php

namespace App\Models;

use App\Collections\PostCollection; // 引入我们自定义的集合类
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Collection as BaseCollection; // 引入基础集合类，用于类型提示

class Post extends Model
{
    // ... 其他模型属性和方法

    /**
     * 创建一个新的 Eloquent 集合实例。
     *
     * @param  array  $models
     * @return \Illuminate\Database\Eloquent\Collection
     */
    public function newCollection(array $models = []): BaseCollection
    {
        return new PostCollection($models);
    }

    // 假设 Post 模型有一个 'tags' 关联关系
    public function tags()
    {
        return $this->belongsToMany(Tag::class);
    }
}

登录后复制

注意，

newCollection

登录后复制

方法的返回类型提示依然是

\Illuminate\Database\Eloquent\Collection

登录后复制

，这是因为

PostCollection

登录后复制

继承自它，符合 LSP (Liskov Substitution Principle)。

步骤 3：实际使用自定义集合

现在，当你在任何地方从

Post

登录后复制

模型获取集合时，你得到的将是

PostCollection

登录后复制

的实例，可以直接调用你定义的方法了。

// 假设在控制器或路由中
use App\Models\Post;

// 获取所有文章
$allPosts = Post::all(); // $allPosts 现在是 PostCollection 的实例

// 获取所有已发布的文章
$publishedPosts = $allPosts->published();

// 计算所有已发布文章的总阅读时长
$totalPublishedReadTime = $publishedPosts->totalReadTime();

// 获取所有关于 'Laravel' 标签的文章
// 注意：如果 withTag 方法内部需要访问关联关系，你可能需要提前加载
$laravelPosts = Post::with('tags')->get()->withTag('Laravel');

// 你也可以链式调用
$featuredPublishedPosts = Post::where('is_featured', true)
                                ->get()
                                ->published()
                                ->totalReadTime(); // 这是一个整数，不是集合

登录后复制

通过这种方式，你的代码会变得更加语义化，业务逻辑被很好地封装在集合内部，提高了代码的复用性和可维护性。这比每次都写

filter()

登录后复制

或

sum()

登录后复制

闭包要优雅得多，尤其是在复杂场景下。

自定义集合在复杂场景下的考量：性能与设计哲学

在复杂应用场景下使用自定义集合，我们不仅要关注其带来的代码整洁性，更要深入思考它可能带来的性能影响和背后的设计哲学。毕竟，工具再好，用错了地方也可能适得其反。

性能考量：N+1 问题与数据预加载

自定义集合的方法，尤其是在处理关联关系时，很容易引入 N+1 查询问题。比如我们前面

PostCollection

登录后复制

中的

withTag()

登录后复制

方法，如果

Post

登录后复制

模型没有预加载

tags

登录后复制

关联关系，那么

filter

登录后复制

内部的

post->tags

登录后复制

每次迭代都会触发一个新的数据库查询，这将导致性能急剧下降。

// 潜在的 N+1 问题
$posts = Post::all(); // 未加载 tags
$laravelPosts = $posts->withTag('Laravel'); // 循环 N 次，每次查询 tags

登录后复制

为了避免这种情况，我们必须确保在创建集合之前，所有自定义方法可能需要的关联数据都已通过 Eager Loading（预加载）加载进来。

// 避免 N+1 问题的正确做法
$posts = Post::with('tags')->get(); // 预加载 tags
$laravelPosts = $posts->withTag('Laravel'); // 现在 withTag 内部不会触发额外查询

登录后复制

自定义集合方法本身不应该成为触发大量新数据库查询的地方。它们的设计哲学是操作已经加载到内存中的数据。如果某个自定义方法确实需要从数据库获取额外数据，那么它应该被视为一个例外，并且需要非常小心地实现，例如通过

load()

登录后复制

或

loadMissing()

登录后复制

方法在集合层面进行批量加载，而不是在每个模型实例上单独查询。但通常来说，我个人会倾向于将这些数据库查询逻辑放在模型或仓库层，确保集合接收到的数据已经足够完整。

设计哲学：何时使用

Illuminate\Support\Collection

登录后复制

与
Illuminate\Database\Eloquent\Collection
登录后复制
？

这是一个经常被忽略但很关键的点。Laravel 提供了两种主要的集合类：

```
Illuminate\Support\Collection
```
登录后复制
: 这是最基础的集合类，可以用于任何 PHP 数组或可迭代对象。它提供了丰富的操作方法，但与 Eloquent 模型无关。
```
Illuminate\Database\Eloquent\Collection
```
登录后复制
: 这是
```
Illuminate\Support\Collection
```
登录后复制
的子类，专门用于承载 Eloquent 模型实例。它额外提供了一些与 Eloquent 相关的便利方法，比如
```
modelKeys()
```
登录后复制
等。

当你为 Eloquent 模型定义自定义集合时，你几乎总是应该继承