Eloquent：集合

简介
可用方法
自定义集合

简介

所有返回多个模型结果的 Eloquent 方法都将返回 Illuminate\Database\Eloquent\Collection 类的实例，包括通过 get 方法检索或通过关系访问的结果。Eloquent 集合对象扩展了 Laravel 的基础集合，因此它自然地继承了许多用于流畅地处理 Eloquent 模型底层数组的方法。请务必查看 Laravel 集合文档，以了解所有这些有用的方法！

所有集合也充当迭代器，允许您像循环简单的 PHP 数组一样循环遍历它们

1use App\Models\User;
2 
3$users = User::where('active', 1)->get();
4 
5foreach ($users as $user) {
6    echo $user->name;
7}

use App\Models\User;

$users = User::where('active', 1)->get();

foreach ($users as $user) {
    echo $user->name;
}

但是，如前所述，集合比数组强大得多，并且公开了各种可以使用直观界面链接的 map / reduce 操作。例如，我们可以删除所有非活动模型，然后收集每个剩余用户的名字

1$names = User::all()->reject(function (User $user) {
2    return $user->active === false;
3})->map(function (User $user) {
4    return $user->name;
5});

$names = User::all()->reject(function (User $user) {
    return $user->active === false;
})->map(function (User $user) {
    return $user->name;
});

Eloquent 集合转换

虽然大多数 Eloquent 集合方法返回 Eloquent 集合的新实例，但 collapse、flatten、flip、keys、pluck 和 zip 方法返回基础集合实例。同样，如果 map 操作返回不包含任何 Eloquent 模型的集合，则它将被转换为基础集合实例。

可用方法

所有 Eloquent 集合都扩展了基础 Laravel 集合对象；因此，它们继承了基础集合类提供的所有强大方法。

此外，Illuminate\Database\Eloquent\Collection 类提供了一组超集方法，以帮助管理您的模型集合。大多数方法返回 Illuminate\Database\Eloquent\Collection 实例；但是，某些方法（如 modelKeys）返回 Illuminate\Support\Collection 实例。

append contains diff except find findOrFail fresh intersect load loadMissing modelKeys makeVisible makeHidden only setVisible setHidden toQuery unique

`append($attributes)`

append 方法可用于指示应为集合中的每个模型附加属性。此方法接受属性数组或单个属性

1$users->append('team');
2 
3$users->append(['team', 'is_admin']);

$users->append('team');

$users->append(['team', 'is_admin']);

`contains($key, $operator = null, $value = null)`

contains 方法可用于确定给定模型实例是否包含在集合中。此方法接受主键或模型实例

1$users->contains(1);
2 
3$users->contains(User::find(1));

$users->contains(1);

$users->contains(User::find(1));

`diff($items)`

diff 方法返回给定集合中不存在的所有模型

1use App\Models\User;
2 
3$users = $users->diff(User::whereIn('id', [1, 2, 3])->get());

use App\Models\User;

$users = $users->diff(User::whereIn('id', [1, 2, 3])->get());

`except($keys)`

except 方法返回不具有给定主键的所有模型

1$users = $users->except([1, 2, 3]);

$users = $users->except([1, 2, 3]);

`find($key)`

find 方法返回主键与给定键匹配的模型。如果 $key 是模型实例，则 find 将尝试返回与主键匹配的模型。如果 $key 是键数组，则 find 将返回所有主键在给定数组中的模型

1$users = User::all();
2 
3$user = $users->find(1);

$users = User::all();

$user = $users->find(1);

`findOrFail($key)`

findOrFail 方法返回主键与给定键匹配的模型，如果在集合中找不到匹配的模型，则抛出 Illuminate\Database\Eloquent\ModelNotFoundException 异常

1$users = User::all();
2 
3$user = $users->findOrFail(1);

$users = User::all();

$user = $users->findOrFail(1);

`fresh($with = [])`

fresh 方法从数据库中检索集合中每个模型的全新实例。此外，任何指定的关系都将被预先加载

1$users = $users->fresh();
2 
3$users = $users->fresh('comments');

$users = $users->fresh();

$users = $users->fresh('comments');

`intersect($items)`

intersect 方法返回给定集合中也存在的所有模型

1use App\Models\User;
2 
3$users = $users->intersect(User::whereIn('id', [1, 2, 3])->get());

use App\Models\User;

$users = $users->intersect(User::whereIn('id', [1, 2, 3])->get());

`load($relations)`

load 方法为集合中的所有模型预先加载给定的关系

1$users->load(['comments', 'posts']);
2 
3$users->load('comments.author');
4 
5$users->load(['comments', 'posts' => fn ($query) => $query->where('active', 1)]);

$users->load(['comments', 'posts']);

$users->load('comments.author');

$users->load(['comments', 'posts' => fn ($query) => $query->where('active', 1)]);

`loadMissing($relations)`

如果关系尚未加载，则 loadMissing 方法为集合中的所有模型预先加载给定的关系

1$users->loadMissing(['comments', 'posts']);
2 
3$users->loadMissing('comments.author');
4 
5$users->loadMissing(['comments', 'posts' => fn ($query) => $query->where('active', 1)]);

$users->loadMissing(['comments', 'posts']);

$users->loadMissing('comments.author');

$users->loadMissing(['comments', 'posts' => fn ($query) => $query->where('active', 1)]);

`modelKeys()`

modelKeys 方法返回集合中所有模型的主键

1$users->modelKeys();
2 
3// [1, 2, 3, 4, 5]

$users->modelKeys();

// [1, 2, 3, 4, 5]

`makeVisible($attributes)`

makeVisible 方法使属性可见，这些属性通常在集合中的每个模型上是“隐藏的”

1$users = $users->makeVisible(['address', 'phone_number']);

$users = $users->makeVisible(['address', 'phone_number']);

`makeHidden($attributes)`

makeHidden 方法隐藏属性，这些属性通常在集合中的每个模型上是“可见的”

1$users = $users->makeHidden(['address', 'phone_number']);

$users = $users->makeHidden(['address', 'phone_number']);

`only($keys)`

only 方法返回具有给定主键的所有模型

1$users = $users->only([1, 2, 3]);

$users = $users->only([1, 2, 3]);

`setVisible($attributes)`

setVisible 方法临时覆盖集合中每个模型上的所有可见属性

1$users = $users->setVisible(['id', 'name']);

$users = $users->setVisible(['id', 'name']);

`setHidden($attributes)`

setHidden 方法临时覆盖集合中每个模型上的所有隐藏属性

1$users = $users->setHidden(['email', 'password', 'remember_token']);

$users = $users->setHidden(['email', 'password', 'remember_token']);

`toQuery()`

toQuery 方法返回一个 Eloquent 查询构建器实例，其中包含集合模型主键上的 whereIn 约束

1use App\Models\User;
2 
3$users = User::where('status', 'VIP')->get();
4 
5$users->toQuery()->update([
6    'status' => 'Administrator',
7]);

use App\Models\User;

$users = User::where('status', 'VIP')->get();

$users->toQuery()->update([
    'status' => 'Administrator',
]);

`unique($key = null, $strict = false)`

unique 方法返回集合中所有唯一的模型。将删除集合中与另一个模型具有相同主键的任何模型

1$users = $users->unique();

$users = $users->unique();

自定义集合

如果您想在使用给定模型时使用自定义 Collection 对象，则可以将 CollectedBy 属性添加到您的模型中

 1<?php
 2 
 3namespace App\Models;
 4 
 5use App\Support\UserCollection;
 6use Illuminate\Database\Eloquent\Attributes\CollectedBy;
 7use Illuminate\Database\Eloquent\Model;
 8 
 9#[CollectedBy(UserCollection::class)]
10class User extends Model
11{
12    // ...
13}

<?php

namespace App\Models;

use App\Support\UserCollection;
use Illuminate\Database\Eloquent\Attributes\CollectedBy;
use Illuminate\Database\Eloquent\Model;

#[CollectedBy(UserCollection::class)]
class User extends Model
{
    // ...
}

或者，您可以在模型上定义 newCollection 方法

 1<?php
 2 
 3namespace App\Models;
 4 
 5use App\Support\UserCollection;
 6use Illuminate\Database\Eloquent\Collection;
 7use Illuminate\Database\Eloquent\Model;
 8 
 9class User extends Model
10{
11    /**
12     * Create a new Eloquent Collection instance.
13     *
14     * @param  array<int, \Illuminate\Database\Eloquent\Model>  $models
15     * @return \Illuminate\Database\Eloquent\Collection<int, \Illuminate\Database\Eloquent\Model>
16     */
17    public function newCollection(array $models = []): Collection
18    {
19        return new UserCollection($models);
20    }
21}

<?php

namespace App\Models;

use App\Support\UserCollection;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * Create a new Eloquent Collection instance.
     *
     * @param  array<int, \Illuminate\Database\Eloquent\Model>  $models
     * @return \Illuminate\Database\Eloquent\Collection<int, \Illuminate\Database\Eloquent\Model>
     */
    public function newCollection(array $models = []): Collection
    {
        return new UserCollection($models);
    }
}

一旦您定义了 newCollection 方法或将 CollectedBy 属性添加到您的模型中，每当 Eloquent 通常返回 Illuminate\Database\Eloquent\Collection 实例时，您都将收到自定义集合的实例。

如果您想为应用程序中的每个模型使用自定义集合，则应在应用程序的所有模型都扩展的基础模型类上定义 newCollection 方法。

序言

入门指南

架构概念

基础知识

深入探讨

安全性

数据库

Eloquent ORM

测试

软件包