# Eloquent : 集合
- [简介](#introduction)
- [可用的方法](#available-methods)
- [自定义集合](#custom-collections)
## 简介
Eloquent 返回的所有结果集都是 `Illuminate\Database\Eloquent\Collection` 对象的实例,包括通过 `get` 方法检索或通过访问关联关系获取到的结果。 Eloquent 的集合对象继承了 Laravel 的 [集合基类](/docs/{{version}}/collections),因此它自然也继承了数十种能优雅地处理 Eloquent 模型底层数组的方法。
而且,所有的集合都可以作为迭代器,你可以像遍历简单的 PHP 数组一样来遍历它们:
$users = App\User::where('active', 1)->get();
foreach ($users as $user) {
echo $user->name;
}
不过,集合比数组更加强大,它通过更加直观的接口暴露出可链式调用的 map / reduce 等操作。例如,让我们移除所有未激活的用户并收集剩余用户的名字:
$users = App\User::all();
$names = $users->reject(function ($user) {
return $user->active === false;
})
->map(function ($user) {
return $user->name;
});
> {note} 大多数 Eloquent 集合方法会返回新的 Eloquent 集合实例,但是 `pluck`, `keys`, `zip`, `collapse`, `flatten` 和 `flip` 方法除外,它们会返回一个 [集合基类](/docs/{{version}}/collections) 实例。同样,如果 `map` 操作返回的集合不包括任何 Eloquent 模型,那么它会被自动转换成集合基类。
## 可用方法
所有 Eloquent 的集合都继承了 [Laravel Collection](/docs/{{version}}/collections#available-methods) 对象; 因此, 他们也继承了所有集合基类提供的强大的方法。
另外,`Illuminate\Database\Eloquent\Collection` 类提供了一套上层的方法来帮你管理你的模型集合。大多数方法返回 `Illuminate\Database\Eloquent\Collection` 实例; 然而,也会有一些方法返回基于 `Illuminate\Support\Collection` 类的实例。
[contains](#method-contains)
[diff](#method-diff)
[except](#method-except)
[find](#method-find)
[fresh](#method-fresh)
[intersect](#method-intersect)
[load](#method-load)
[loadMissing](#method-loadMissing)
[modelKeys](#method-modelKeys)
[makeVisible](#method-makeVisible)
[makeHidden](#method-makeHidden)
[only](#method-only)
[unique](#method-unique)
#### `contains($key, $operator = null, $value = null)`
`contains` 方法可用于判断集合中是否包含指定的模型实例。这个方法接收一个主键或者模型实例:
$users->contains(1);
$users->contains(User::find(1));
#### `diff($items)`
`diff` 方法返回不在给定集合中的所有模型:
use App\User;
$users = $users->diff(User::whereIn('id', [1, 2, 3])->get());
#### `except($keys)`
`except` 方法返回给定主键外的所有模型:
$users = $users->except([1, 2, 3]);
#### `find($key)` {#collection-method .first-collection-method}
`find` 方法查找给定主键的模型。如果 `$key` 是一个模型实例, `find` 将会尝试返回与主键匹配的模型。 如果 `$key` 是一个关联数组, `find` 将会使用 `whereIn()` 返回所有匹配 `$keys` 的模型:
$users = User::all();
$user = $users->find(1);
#### `fresh($with = [])`
`fresh` 方法从数据库检索集合中的每个模型的新实例。 此外,任何指定的关系都会被预先加载:
$users = $users->fresh();
$users = $users->fresh('comments');
#### `intersect($items)`
`intersect` 方法返回给定集合中也存在的所有模型:
use App\User;
$users = $users->intersect(User::whereIn('id', [1, 2, 3])->get());
#### `load($relations)`
`load` 方法会提前加载集合中所有模型的指定关系:
$users->load('comments', 'posts');
$users->load('comments.author');
#### `loadMissing($relations)`
如果尚未加载关系,`loadMissing` 方法将会为集合中的所有模型加载给定的关系
$users->loadMissing('comments', 'posts');
$users->loadMissing('comments.author');
#### `modelKeys()`
`modelKeys` 方法返回集合中所有模型的主键:
$users->modelKeys();
// [1, 2, 3, 4, 5]
#### `makeVisible($attributes)`
`makeVisible` 方法显示集合中的每个模型的指定隐藏属性:
$users = $users->makeVisible(['address', 'phone_number']);
#### `makeHidden($attributes)`
`makeHidden` 隐藏集合中的每个模型指定属性:
$users = $users->makeHidden(['address', 'phone_number']);
#### `only($keys)`
`only` 方法返回给定主键的所有模型:
$users = $users->only([1, 2, 3]);
#### `unique($key = null, $strict = false)`
`unique` 方法返回集合中的所有唯一模型。并且删除与集合中另一个模型有相同主键的同一类型的所有模型
$users = $users->unique();
## 自定义集合
如果你需要使用自定义 `Collection` 对象与自己的扩展方法一起使用, 可以在你的模型上重写 `newCollection` 方法: