集合
简介
Illuminate\Support\Collection
类提供一个流畅、便利的封装来操控数组数据。如下面的示例代码,我们用 collect
函数从数组中创建新的 集合实例,对每一个元素运行 strtoupper
函数,然后移除所有的空元素:
$collection = collect(['taylor', 'abigail', null])->map(function ($name) {
return strtoupper($name);
})
->reject(function ($name) {
return empty($name);
});
如你所见,Collection
类支持链式调用,一般来说,每一个 Collection
方法会返回一个全新的 Collection
实例,你可以放心地进行链接调用。
创建集合
如上所述,collect
辅助函数会利用传入的数组生成一个新的 Illuminate\Support\Collection
实例。所以要创建一个集合就这么简单:
$collection = collect([1, 2, 3]);
默认 Eloquent 模型的集合总是以 Collection
实例返回;然而,你可以随意的在你应用程序中使用 Collection
类。
可用的方法
在这份文档剩余的部份,我们将会探讨 Collection
类的所有方法。要记得的是,所有方法都支持链式调用,几乎所有的方法都会返回新的 Collection
实例,让你保留原版的集合以备不时之需。
你可以从这张数据库表中选择任一方法看使用例子:
all avg chunk collapse contains count diff each every except filter first flatten flip forget forPage get groupBy has implode intersect isEmpty keyBy keys last map max merge min only pluck pop prepend pull push put random reduce reject reverse search shift shuffle slice sort sortBy sortByDesc splice sum take toArray toJson transform unique values where whereLoose zip
方法清单
all()
返回该集合所代表的底层 数组
:
collect([1, 2, 3])->all();
// [1, 2, 3]
avg()
返回集合中所有项目的平均值:
collect([1, 2, 3, 4, 5])->avg();
// 3
如果集合包含了嵌套数组或对象,你可以通过传递「键」来指定使用哪些值计算平均值:
$collection = collect([
['name' => 'JavaScript: The Good Parts', 'pages' => 176],
['name' => 'JavaScript: The Definitive Guide', 'pages' => 1096],
]);
$collection->avg('pages');
// 636
chunk()
将集合拆成多个指定大小的较小集合:
$collection = collect([1, 2, 3, 4, 5, 6, 7]);
$chunks = $collection->chunk(4);
$chunks->toArray();
// [[1, 2, 3, 4], [5, 6, 7]]
这个方法在适用于网格系统如 Bootstrap 的 视图 。想像你有一个 Eloquent 模型的集合要显示在一个网格内:
@foreach ($products->chunk(3) as $chunk)
<div class="row">
@foreach ($chunk as $product)
<div class="col-xs-4">{{ $product->name }}</div>
@endforeach
</div>
@endforeach
collapse()
将多个数组组成的集合合成单个数组集合:
$collection = collect([[1, 2, 3], [4, 5, 6], [7, 8, 9]]);
$collapsed = $collection->collapse();
$collapsed->all();
// [1, 2, 3, 4, 5, 6, 7, 8, 9]
contains()
判断集合是否含有指定项目:
$collection = collect(['name' => 'Desk', 'price' => 100]);
$collection->contains('Desk');
// true
$collection->contains('New York');
// false
你可以将一对键/值传入 contains
方法,用来判断该组合是否存在于集合内:
$collection = collect([
['product' => 'Desk', 'price' => 200],
['product' => 'Chair', 'price' => 100],
]);
$collection->contains('product', 'Bookcase');
// false
最后,你也可以传入一个回调函数到 contains
方法内运行你自己的判断语句:
$collection = collect([1, 2, 3, 4, 5]);
$collection->contains(function ($key, $value) {
return $value > 5;
});
// false
count()
返回该集合内的项目总数:
$collection = collect([1, 2, 3, 4]);
$collection->count();
// 4
diff()
将集合与其它集合或纯 PHP 数组
进行比较:
$collection = collect([1, 2, 3, 4, 5]);
$diff = $collection->diff([2, 4, 6, 8]);
$diff->all();
// [1, 3, 5]
each()
遍历集合中的项目,并将之传入回调函数:
$collection = $collection->each(function ($item, $key) {
//
});
回调函数返回 false
以中断循环:
$collection = $collection->each(function ($item, $key) {
if (/* some condition */) {
return false;
}
});
every()
创建一个包含每 第 n 个 元素的新集合:
$collection = collect(['a', 'b', 'c', 'd', 'e', 'f']);
$collection->every(4);
// ['a', 'e']
你可以选择性的传递偏移值作为第二个参数:
$collection->every(4, 1);
// ['b', 'f']
except()
返回集合中除了指定键的所有项目:
$collection = collect(['product_id' => 1, 'name' => 'Desk', 'price' => 100, 'discount' => false]);
$filtered = $collection->except(['price', 'discount']);
$filtered->all();
// ['product_id' => 1, 'name' => 'Desk']
与 except
相反的方法请查看 only。
filter()
使用回调函数筛选集合,只留下那些通过判断测试的项目:
$collection = collect([1, 2, 3, 4]);
$filtered = $collection->filter(function ($item) {
return $item > 2;
});
$filtered->all();
// [3, 4]
与 filter
相反的方法可以查看 reject。
first()
返回集合第一个通过指定测试的元素:
collect([1, 2, 3, 4])->first(function ($key, $value) {
return $value > 2;
});
// 3
你也可以不传入参数使用 first
方法以获取集合中第一个元素。如果集合是空的,则会返回 null
:
collect([1, 2, 3, 4])->first();
// 1
flatten()
将多维集合转为一维集合:
$collection = collect(['name' => 'taylor', 'languages' => ['php', 'javascript']]);
$flattened = $collection->flatten();
$flattened->all();
// ['taylor', 'php', 'javascript'];
flip()
将集合中的键和对应的数值进行互换:
$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
$flipped = $collection->flip();
$flipped->all();
// ['taylor' => 'name', 'laravel' => 'framework']
forget()
通过集合的键来移除掉集合中的一个项目:
$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
$collection->forget('name');
$collection->all();
// [framework' => 'laravel']
与大多数其它集合的方法不同,forget
不会返回修改过后的新集合;它会直接修改调用它的集合。
forPage()
返回可用来在指定页码显示项目的新集合:
$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9]);
$chunk = $collection->forPage(2, 3);
$chunk->all();
// [4, 5, 6]
这个方法需要「页码」和「每页显示数量」。
get()
返回指定键的项目。如果该键不存在,则返回 null
:
$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
$value = $collection->get('name');
// taylor
你可以选择性地传入一个默认值作为第二个参数:
$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
$value = $collection->get('foo', 'default-value');
// default-value
你甚至可以传入回调函数当默认值。如果指定的键不存在,就会返回回调函数的运行结果:
$collection->get('email', function () {
return 'default-value';
});
// default-value
groupBy()
根据指定的「键」为集合内的项目分组:
$collection = collect([
['account_id' => 'account-x10', 'product' => 'Chair'],
['account_id' => 'account-x10', 'product' => 'Bookcase'],
['account_id' => 'account-x11', 'product' => 'Desk'],
]);
$grouped = $collection->groupBy('account_id');
$grouped->toArray();
/*
[
'account-x10' => [
['account_id' => 'account-x10', 'product' => 'Chair'],
['account_id' => 'account-x10', 'product' => 'Bookcase'],
],
'account-x11' => [
['account_id' => 'account-x11', 'product' => 'Desk'],
],
]
*/
除了传入字符串的「键」之外,你也可以传入回调函数。该函数应该返回你希望用来分组的键的值。
$grouped = $collection->groupBy(function ($item, $key) {
return substr($item['account_id'], -3);
});
$grouped->toArray();
/*
[
'x10' => [
['account_id' => 'account-x10', 'product' => 'Chair'],
['account_id' => 'account-x10', 'product' => 'Bookcase'],
],
'x11' => [
['account_id' => 'account-x11', 'product' => 'Desk'],
],
]
*/
has()
检查集合中是否含有指定的「键」:
$collection = collect(['account_id' => 1, 'product' => 'Desk']);
$collection->has('email');
// false
implode()
implode
方法合并集合中的项目。它的参数依集合中的项目类型而定。
假如集合含有数组或对象,你应该传入你希望连接的属性的「键」,以及你希望放在数值之间的拼接字符串:
$collection = collect([
['account_id' => 1, 'product' => 'Desk'],
['account_id' => 2, 'product' => 'Chair'],
]);
$collection->implode('product', ', ');
// Desk, Chair
假如集合只含有简单的字符串或数字,则只需要传入拼接的字符串作为该方法的唯一参数即可:
collect([1, 2, 3, 4, 5])->implode('-');
// '1-2-3-4-5'
intersect()
移除任何指定 数组
或集合内所没有的数值:
$collection = collect(['Desk', 'Sofa', 'Chair']);
$intersect = $collection->intersect(['Desk', 'Chair', 'Bookcase']);
$intersect->all();
// [0 => 'Desk', 2 => 'Chair']
相当于取「交集」。
isEmpty()
如果集合是空的,isEmpty
方法会返回 true
:否则返回 false
:
collect([])->isEmpty();
// true
keyBy()
以指定键的值作为集合项目的键:
$collection = collect([
['product_id' => 'prod-100', 'name' => 'desk'],
['product_id' => 'prod-200', 'name' => 'chair'],
]);
$keyed = $collection->keyBy('product_id');
$keyed->all();
/*
[
'prod-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
'prod-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
]
*/
如果多个项目有同样的键,只有最后一个会出现在新的集合内。
你也可以传入自己的回调函数,该函数应该返回集合的键的值:
$keyed = $collection->keyBy(function ($item) {
return strtoupper($item['product_id']);
});
$keyed->all();
/*
[
'PROD-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
'PROD-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
]
*/