- 集合
- 简介
- 可用方法
- 方法列表
- all()
- average()
- avg()
- chunk()
- collapse()
- combine()
- collect()
- concat()
- contains()
- containsStrict()
- count()
- countBy()
- crossJoin()
- dd()
- diff()
- diffAssoc()
- diffKeys()
- dump()
- duplicates()
- duplicatesStrict()
- each()
- eachSpread()
- every()
- except()
- filter()
- first()
- firstWhere()
- flatMap()
- flatten()
- flip()
- forget()
- forPage()
- get()
- groupBy()
- has()
- implode()
- intersect()
- intersectByKeys()
- isEmpty()
- isNotEmpty()
- join()
- keyBy()
- keys()
- last()
- macro()
- make()
- map()
- mapInto()
- mapSpread()
- mapToGroups()
- mapWithKeys()
- max()
- median()
- merge()
- mergeRecursive()
- min()
- mode()
- nth()
- only()
- pad()
- partition()
- pipe()
- pluck()
- pop()
- prepend()
- pull()
- push()
- put()
- random()
- reduce()
- reject()
- replace()
- replaceRecursive()
- reverse()
- search()
- shift()
- shuffle()
- skip()
- slice()
- some()
- sort()
- sortBy()
- sortByDesc()
- sortDesc()
- sortKeys()
- sortKeysDesc()
- splice()
- split()
- sum()
- take()
- tap()
- times()
- toArray()
- toJson()
- transform()
- union()
- unique()
- uniqueStrict()
- unless()
- unlessEmpty()
- unlessNotEmpty()
- unwrap()
- values()
- when()
- whenEmpty()
- whenNotEmpty()
- where()
- whereStrict()
- whereBetween()
- whereIn()
- whereInStrict()
- whereInstanceOf()
- whereNotBetween()
- whereNotIn()
- whereNotInStrict()
- whereNotNull()
- whereNull()
- wrap()
- zip()
- 高阶消息传递
- 懒集合
集合
简介
Illuminate\Support\Collection
类提供了一个更具可读性和更便于处理数组数据的封装。具体请查看下方示例代码。我们使用 collect
辅助函数从数组中创建一个新的集合实例,对其中每一个元素执行strtoupper
函数之后再删除所有的空元素:
$collection = collect(['taylor', 'abigail', null])->map(function ($name) {
return strtoupper($name);
})
->reject(function ($name) {
return empty($name);
});
正如你所见, Collection
类允许你链式调用其它方法,以达到在底层数组上流畅的执行 map 和 reduce 操作,通常,集合是不可变的,这意味着每一个Collection
方法都会返回一个新的 Collection
实例。
创建集合
如上所述,collect
辅助函数会为指定的数组返回一个新的Illuminate\Support\Collection
实例。因此,我们可以非常容易的创建一个结合:
$collection = collect([1, 2, 3]);
Tip: Eloquent 查询结果总是返回
Collection
实例。
扩展集合
集合都是「可宏扩展」(macroable) 的,它允许你在执行时将其它方法添加到 Collection 类。例如,通过下面的代码在Collection
类中添加一个toUpper
方法:
use Illuminate\Support\Collection;
use Illuminate\Support\Str;
Collection::macro('toUpper', function () {
return $this->map(function ($value) {
return Str::upper($value);
});
});
$collection = collect(['first', 'second']);
$upper = $collection->toUpper();
// ['FIRST', 'SECOND']
通常,你应该在服务提供者 内声明集合宏。
可用方法
接下来,我们将讨论每个 Collection
类可用的方法。记住,所有这些方法都可以链式调用以流畅地操作底层数组。此外,几乎所有方法都返回一个新的 Collection
实例,允许你在需要时保存集合的原始副本:
all average avg chunk collapse collect combine concat contains containsStrict count countBy crossJoin dd diff diffAssoc diffKeys dump duplicates duplicatesStrict each eachSpread every except filter first firstWhere flatMap flatten flip forget forPage get groupBy has implode intersect intersectByKeys isEmpty isNotEmpty join keyBy keys last macro make map mapInto mapSpread mapToGroups mapWithKeys max median merge mergeRecursive min mode nth only pad partition pipe pluck pop prepend pull push put random reduce reject replace replaceRecursive reverse search shift shuffle skip slice some sort sortBy sortByDesc sortDesc sortKeys sortKeysDesc splice split sum take tap times toArray toJson transform union unique uniqueStrict unless unlessEmpty unlessNotEmpty unwrap values when whenEmpty whenNotEmpty where whereStrict whereBetween whereIn whereInStrict whereInstanceOf whereNotBetween whereNotIn whereNotInStrict whereNotNull whereNull wrap zip
方法列表
all()
all
方法返回代表集合的底层数组:
collect([1, 2, 3])->all();
// [1, 2, 3]
average()
avg
方法的别名。
avg()
avg
方法返回指定键的 平均值 :
$average = collect([['foo' => 10], ['foo' => 10], ['foo' => 20], ['foo' => 40]])->avg('foo');
// 20
$average = collect([1, 1, 2, 4])->avg();
// 2
chunk()
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()
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]
combine()
combine
方法将一个集合的值作为键,与另一个数组或集合的值进行结合:
$collection = collect(['name', 'age']);
$combined = $collection->combine(['George', 29]);
$combined->all();
// ['name' => 'George', 'age' => 29]
collect()
collect
方法返回一个包含当前集合所含元素的新 Collection
实例:
$collectionA = collect([1, 2, 3]);
$collectionB = $collectionA->collect();
$collectionB->all();
// [1, 2, 3]
collect
方法从根本上对将 懒集合 转换为标准 Collection
实例有用:
$lazyCollection = LazyCollection::make(function () {
yield 1;
yield 2;
yield 3;
});
$collection = $lazyCollection->collect();
get_class($collection);
// 'Illuminate\Support\Collection'
$collection->all();
// [1, 2, 3]
{提示} 当你有个
Enumerable
实例并需要一个非懒集合实例时,collect
方法相当有用。由于collect()
是Enumerable
契约的一部分,你可以安全地使用它以获取一个Collection
实例。
concat()
concat
方法在集合的末端附加指定的 数组
或集合值:
$collection = collect(['John Doe']);
$concatenated = $collection->concat(['Jane Doe'])->concat(['name' => 'Johnny Doe']);
$concatenated->all();
// ['John Doe', 'Jane Doe', 'Johnny Doe']
contains()
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 ($value, $key) {
return $value > 5;
});
// false
contains
方法用“松散”比较检查元素值,意味着整数值的字符串会被视同等值的整数。用 containsStrict
方法使用“严格”比较过滤。
containsStrict()
这个方法和 contains
方法类似;但是它却是使用了「严格」比较来比较所有的值。
技巧:这个方法的行为当使用 Eloquent Collections会被重写。
count()
count
方法返回这个集合内集合项的总数量:
$collection = collect([1, 2, 3, 4]);
$collection->count();
// 4
countBy()
countBy
方法计算集合中每个值的出现次数。默认情况下,该方法计算每个元素的出现次数:
$collection = collect([1, 2, 2, 2, 3]);
$counted = $collection->countBy();
$counted->all();
// [1 => 1, 2 => 3, 3 => 1]
但是,你也可以向 countBy
传递一个回调函数来计算自定义的值出现的次数:
$collection = collect(['alice@gmail.com', 'bob@yahoo.com', 'carlos@gmail.com']);
$counted = $collection->countBy(function ($email) {
return substr(strrchr($email, "@"), 1);
});
$counted->all();
// ['gmail.com' => 2, 'yahoo.com' => 1]
crossJoin()
crossJoin
方法交叉连接指定数组或集合的值,返回所有可能排列的笛卡尔积:
$collection = collect([1, 2]);
$matrix = $collection->crossJoin(['a', 'b']);
$matrix->all();
/*
[
[1, 'a'],
[1, 'b'],
[2, 'a'],
[2, 'b'],
]
*/
$collection = collect([1, 2]);
$matrix = $collection->crossJoin(['a', 'b'], ['I', 'II']);
$matrix->all();
/*
[
[1, 'a', 'I'],
[1, 'a', 'II'],
[1, 'b', 'I'],
[1, 'b', 'II'],
[2, 'a', 'I'],
[2, 'a', 'II'],
[2, 'b', 'I'],
[2, 'b', 'II'],
]
*/
dd()
dd
方法用于打印集合元素并中断脚本执行:
$collection = collect(['John Doe', 'Jane Doe']);
$collection->dd();
/*
Collection {
#items: array:2 [
0 => "John Doe"
1 => "Jane Doe"
]
}
*/
如果你不想中断执行脚本,请使用 dump
方法替代。
diff()
diff
方法将集合与其它集合或者 PHP 数组进行值的比较。然后返回原集合中存在而指定集合中不存在的值:
$collection = collect([1, 2, 3, 4, 5]);
$diff = $collection->diff([2, 4, 6, 8]);
$diff->all();
// [1, 3, 5]
技巧:这个方法的行为当使用Eloquent Collections时会被重写。
diffAssoc()
diffAssoc
方法与另外一个集合或基于 PHP 数组的键 / 值对(keys and values
)进行比较。这个方法将会返回原集合不存在于指定集合的键 / 值对:
$collection = collect([
'color' => 'orange',
'type' => 'fruit',
'remain' => 6
]);
$diff = $collection->diffAssoc([
'color' => 'yellow',
'type' => 'fruit',
'remain' => 3,
'used' => 6,
]);
$diff->all();
// ['color' => 'orange', 'remain' => 6]
diffKeys()
diffKeys
方法和另外一个集合或 PHP 数组的键(keys
)进行比较,然后返回原集合中存在而指定集合中不存在键所对应的键 / 值对:
$collection = collect([
'one' => 10,
'two' => 20,
'three' => 30,
'four' => 40,
'five' => 50,
]);
$diff = $collection->diffKeys([
'two' => 2,
'four' => 4,
'six' => 6,
'eight' => 8,
]);
$diff->all();
// ['one' => 10, 'three' => 30, 'five' => 50]
dump()
dump
方法用于打印集合项:
$collection = collect(['John Doe', 'Jane Doe']);
$collection->dump();
/*
Collection {
#items: array:2 [
0 => "John Doe"
1 => "Jane Doe"
]
}
*/
如果要在打印集合后终止执行脚本,请使用 dd
方法代替。
duplicates()
duplicates
方法从集合中检索并返回重复的值:
$collection = collect(['a', 'b', 'a', 'c', 'b']);
$collection->duplicates();
// [2 => 'a', 4 => 'b']
如果集合包含数组或对象,则可以传递希望检查重复值的属性的键:
$employees = collect([
['email' => 'abigail@example.com', 'position' => 'Developer'],
['email' => 'james@example.com', 'position' => 'Designer'],
['email' => 'victoria@example.com', 'position' => 'Developer'],
])
$employees->duplicates('position');
// [2 => 'Developer']
duplicatesStrict()
此方法与 duplicates
方法具有相同的签名;但是,所有值都以「严格」的方式进行比较。
each()
each
方法用于循环集合项并将其传递到回调函数中:
$collection->each(function ($item, $key) {
//
});
如果你想中断对集合项的循环,那么就在你的回调函数中返回 false
:
$collection->each(function ($item, $key) {
if (/* some condition */) {
return false;
}
});
eachSpread()
eachSpread
方法用于循环集合项,将每个嵌套集合项的值传递给回调函数:
$collection = collect([['John Doe', 35], ['Jane Doe', 33]]);
$collection->eachSpread(function ($name, $age) {
//
});
你可以通过在回调函数里返回 false
来中断循环:
$collection->eachSpread(function ($name, $age) {
return false;
});
every()
every
方法可用于验证集合中的每一个元素是否通过指定的条件测试:
collect([1, 2, 3, 4])->every(function ($value, $key) {
return $value > 2;
});
// false
如果集合为空, every
将返回 true :$collection = collect([]);
$collection->every(function ($value, $key) {
return $value > 2;
});
// true
except()
except
方法返回集合中除了指定键之外的所有集合项:
$collection = collect(['product_id' => 1, 'price' => 100, 'discount' => false]);
$filtered = $collection->except(['price', 'discount']);
$filtered->all();
// ['product_id' => 1]
与 except
对应的是 only 方法。
技巧:这个方法的行为当使用 Eloquent Collections时会被重写。
filter()
filter
方法使用给定的回调函数过滤集合,只保留那些通过指定条件测试的集合项:
$collection = collect([1, 2, 3, 4]);
$filtered = $collection->filter(function ($value, $key) {
return $value > 2;
});
$filtered->all();
// [3, 4]
如果没有提供回调函数,集合中所有返回 false
的元素都会被移除:
$collection = collect([1, 2, 3, null, false, '', 0, []]);
$collection->filter()->all();
// [1, 2, 3]
filter
对应的是 reject 方法。
first()
first
方法返回集合中通过指定条件测试的第一个元素:
collect([1, 2, 3, 4])->first(function ($value, $key) {
return $value > 2;
});
// 3
你也可以不传入参数调用 first
方法来获取集合中的第一个元素。如果集合为空,则会返回 null
:
collect([1, 2, 3, 4])->first();
// 1
firstWhere()
firstWhere
方法返回集合中含有指定键 / 值对的第一个元素:
$collection = collect([
['name' => 'Regena', 'age' => null],
['name' => 'Linda', 'age' => 14],
['name' => 'Diego', 'age' => 23],
['name' => 'Linda', 'age' => 84],
]);
$collection->firstWhere('name', 'Linda');
// ['name' => 'Linda', 'age' => 14]
你也可以使用运算符来调用 firstWhere
方法:
$collection->firstWhere('age', '>=', 18);
// ['name' => 'Diego', 'age' => 23]
和 where 方法一样,你可以将一个参数传递给 firstWhere
方法。在这种情况下, firstWhere
方法将返回指定键的值为「真」的第一个集合项:
$collection->firstWhere('age');
// ['name' => 'Linda', 'age' => 14]
flatMap()
flatMap
方法遍历集合并将其中的每个值传递到给定的回调函数。可以通过回调函数修改集合项并返回它们,从而形成一个被修改过的新集合。然后,集合转化的数组是同级的:
$collection = collect([
['name' => 'Sally'],
['school' => 'Arkansas'],
['age' => 28]
]);
$flattened = $collection->flatMap(function ($values) {
return array_map('strtoupper', $values);
});
$flattened->all();
// ['name' => 'SALLY', 'school' => 'ARKANSAS', 'age' => '28'];
flatten()
flatten
方法将多维集合转为一维集合:
$collection = collect(['name' => 'taylor', 'languages' => ['php', 'javascript']]);
$flattened = $collection->flatten();
$flattened->all();
// ['taylor', 'php', 'javascript'];
你可以选择性地传入「深度」参数:
$collection = collect([
'Apple' => [
['name' => 'iPhone 6S', 'brand' => 'Apple'],
],
'Samsung' => [
['name' => 'Galaxy S7', 'brand' => 'Samsung']
],
]);
$products = $collection->flatten(1);
$products->values()->all();
/*
[
['name' => 'iPhone 6S', 'brand' => 'Apple'],
['name' => 'Galaxy S7', 'brand' => 'Samsung'],
]
*/
在这个例子里,调用 flatten
时不传入深度参数的话也会将嵌套数组转成一维的,然后返回 ['iPhone 6S', 'Apple', 'Galaxy S7', 'Samsung']
。传入深度参数能让你限制设置返回数组的层数。
flip()
flip
方法将集合的键和对应的值进行互换:
$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
$flipped = $collection->flip();
$flipped->all();
// ['taylor' => 'name', 'laravel' => 'framework']
forget()
forget
方法将通过指定的键来移除集合中对应的内容:
$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
$collection->forget('name');
$collection->all();
// ['framework' => 'laravel']
注意:与大多数集合的方法不同的是,
forget
不会返回修改后的新集合;它会直接修改原集合。
forPage()
forPage
方法返回一个含有指定页码数集合项的新集合。这个方法接受页码数作为其第一个参数,每页显示的项数作为其第二个参数:
$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9]);
$chunk = $collection->forPage(2, 3);
$chunk->all();
// [4, 5, 6]
get()
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()
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'],
],
]
*/
可以传递一个数组用于多重分组标准。每一个数组元素将对应多维数组内的相应级别:
$data = new Collection([
10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
30 => ['user' => 3, 'skill' => 2, 'roles' => ['Role_1']],
40 => ['user' => 4, 'skill' => 2, 'roles' => ['Role_2']],
]);
$result = $data->groupBy([
'skill',
function ($item) {
return $item['roles'];
},
], $preserveKeys = true);
/*
[
1 => [
'Role_1' => [
10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
],
'Role_2' => [
20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
],
'Role_3' => [
10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
],
],
2 => [
'Role_1' => [
30 => ['user' => 3, 'skill' => 2, 'roles' => ['Role_1']],
],
'Role_2' => [
40 => ['user' => 4, 'skill' => 2, 'roles' => ['Role_2']],
],
],
];
*/
has()
has
方法判断集合中是否存在指定键:
$collection = collect(['account_id' => 1, 'product' => 'Desk', 'amount' => 5]);
$collection->has('product');
// true
$collection->has(['product', 'amount']);
// true
$collection->has(['amount', 'price']);
// 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()
intersect
方法从原集合中移除在指定 array
或集合中不存在的值。生成的集合将会保留原集合的键:
$collection = collect(['Desk', 'Sofa', 'Chair']);
$intersect = $collection->intersect(['Desk', 'Chair', 'Bookcase']);
$intersect->all();
// [0 => 'Desk', 2 => 'Chair']
提示:使用 Eloquent Collections 方法时,会修改此方法的行为。
intersectByKeys()
intersectByKeys
方法从原集合中移除在指定 array
或集合中不存在的任何键:
$collection = collect([
'serial' => 'UX301', 'type' => 'screen', 'year' => 2009
]);
$intersect = $collection->intersectByKeys([
'reference' => 'UX404', 'type' => 'tab', 'year' => 2011
]);
$intersect->all();
// ['type' => 'screen', 'year' => 2009]
isEmpty()
如果集合为空, isEmpty
方法返回 true
,否则返回 false
:
collect([])->isEmpty();
// true
isNotEmpty()
如果集合不为空,isNotEmpty
方法返回 true
,否则返回 false
:
collect([])->isNotEmpty();
// false
join()
join
方法会将集合中的值用字符串连接:
collect(['a', 'b', 'c'])->join(', '); // 'a, b, c'
collect(['a', 'b', 'c'])->join(', ', ', and '); // 'a, b, and c'
collect(['a', 'b'])->join(', ', ' and '); // 'a and b'
collect(['a'])->join(', ', ' and '); // 'a'
collect([])->join(', ', ' and '); // ''
keyBy()
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'],
]
*/
keys()
keys
方法返回集合中所有的键:
$collection = collect([
'prod-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
'prod-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
]);
$keys = $collection->keys();
$keys->all();
// ['prod-100', 'prod-200']
last()
last
方法返回集合中通过指定条件测试的最后一个元素:
collect([1, 2, 3, 4])->last(function ($value, $key) {
return $value < 3;
});
// 2
不传入参数的情况下, last
方法会获取集合中最后一个元素。如果集合为空,方法将返回 null
:
collect([1, 2, 3, 4])->last();
// 4
macro()
静态 macro
方法允许你在运行时将方法添加至 Collection
类。关于更多信息,请参阅 扩展集合 的文档。
make()
静态 make
方法可以创建一个新的集合实例。请参照 创建集合 部分。
map()
map
方法遍历集合并将每一个值传入给定的回调函数。该回调函数可以任意修改集合项并返回,从而生成被修改过集合项的新集合:
$collection = collect([1, 2, 3, 4, 5]);
$multiplied = $collection->map(function ($item, $key) {
return $item * 2;
});
$multiplied->all();
// [2, 4, 6, 8, 10]
注意:与其他大多数集合方法一样,
map
会返回一个新的集合实例;它不会修改原集合。如果你想修改原集合,请使用transform
方法。
mapInto()
mapInto()
方法可以迭代集合,通过将值传递给构造函数来创建给定类的新实例:
class Currency
{
/**
* Create a new currency instance.
*
* @param string $code
* @return void
*/
function __construct(string $code)
{
$this->code = $code;
}
}
$collection = collect(['USD', 'EUR', 'GBP']);
$currencies = $collection->mapInto(Currency::class);
$currencies->all();
// [Currency('USD'), Currency('EUR'), Currency('GBP')]
mapSpread()
mapSpread
方法可以迭代集合,将每个嵌套项值给指定的回调函数。该回调函数可以自由修改该集合项并返回,从而生成被修改过集合项的新集合:
$collection = collect([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
$chunks = $collection->chunk(2);
$sequence = $chunks->mapSpread(function ($even, $odd) {
return $even + $odd;
});
$sequence->all();
// [1, 5, 9, 13, 17]
mapToGroups()
mapToGroups
方法通过给定的回调函数对集合项进行分组。该回调函数应该返回一个包含单个键 / 值对的关联数组,从而生成一个分组值的新集合:
$collection = collect([
[
'name' => 'John Doe',
'department' => 'Sales',
],
[
'name' => 'Jane Doe',
'department' => 'Sales',
],
[
'name' => 'Johnny Doe',
'department' => 'Marketing',
]
]);
$grouped = $collection->mapToGroups(function ($item, $key) {
return [$item['department'] => $item['name']];
});
$grouped->toArray();
/*
[
'Sales' => ['John Doe', 'Jane Doe'],
'Marketing' => ['Johnny Doe'],
]
*/
$grouped->get('Sales')->all();
// ['John Doe', 'Jane Doe']
mapWithKeys()
mapWithKeys
方法遍历集合并将每个值传入给定的回调函数。该回调函数将返回一个包含单个键 / 值对的关联数组:
$collection = collect([
[
'name' => 'John',
'department' => 'Sales',
'email' => 'john@example.com'
],
[
'name' => 'Jane',
'department' => 'Marketing',
'email' => 'jane@example.com'
]
]);
$keyed = $collection->mapWithKeys(function ($item) {
return [$item['email'] => $item['name']];
});
$keyed->all();
/*
[
'john@example.com' => 'John',
'jane@example.com' => 'Jane',
]
*/
max()
max
方法返回指定键的最大值:
$max = collect([['foo' => 10], ['foo' => 20]])->max('foo');
// 20
$max = collect([1, 2, 3, 4, 5])->max();
// 5
median()
median
方法返回指定键的 中间值 :
$median = collect([['foo' => 10], ['foo' => 10], ['foo' => 20], ['foo' => 40]])->median('foo');
// 15
$median = collect([1, 1, 2, 4])->median();
// 1.5
merge()
merge
方法将合并指定的数组或集合到原集合。如果给定的集合项的字符串键与原集合中的字符串键相匹配,则指定集合项的值将覆盖原集合的值:
$collection = collect(['product_id' => 1, 'price' => 100]);
$merged = $collection->merge(['price' => 200, 'discount' => false]);
$merged->all();
// ['product_id' => 1, 'price' => 200, 'discount' => false]
如果给定的集合项为数字,则这些值将会追加在集合的最后:
$collection = collect(['Desk', 'Chair']);
$merged = $collection->merge(['Bookcase', 'Door']);
$merged->all();
// ['Desk', 'Chair', 'Bookcase', 'Door']
mergeRecursive()
mergeRecursive
方法以递归的形式合并给定的数组或集合到原集合中,如果给定集合项的字符串键与原集合的字符串键一致,则会将给定的集合项的值以递归的形式合并到原集合的相同键中。
$collection = collect(['product_id' => 1, 'price' => 100]);
$merged = $collection->mergeRecursive(['product_id' => 2, 'price' => 200, 'discount' => false]);
$merged->all();
// ['product_id' => [1, 2], 'price' => [100, 200], 'discount' => false]
min()
min
方法返回指定键的最小值:
$min = collect([['foo' => 10], ['foo' => 20]])->min('foo');
// 10
$min = collect([1, 2, 3, 4, 5])->min();
// 1
mode()
mode
方法返回指定键的 众数) :
$mode = collect([['foo' => 10], ['foo' => 10], ['foo' => 20], ['foo' => 40]])->mode('foo');
// [10]
$mode = collect([1, 1, 2, 4])->mode();
// [1]
nth()
nth
方法创建由每隔 n 个元素组成的一个新集合:
$collection = collect(['a', 'b', 'c', 'd', 'e', 'f']);
$collection->nth(4);
// ['a', 'e']
你也可以设置指定的偏移位置作为第二个参数:
$collection->nth(4, 1);
// ['b', 'f']
only()
only
方法返回集合中所有指定键的集合项:
$collection = collect(['product_id' => 1, 'name' => 'Desk', 'price' => 100, 'discount' => false]);
$filtered = $collection->only(['product_id', 'name']);
$filtered->all();
// ['product_id' => 1, 'name' => 'Desk']
与 only
对应的是 except 方法。
注意: 此方法在使用 Eloquent Collections时会被更改。
pad()
pad
方法将使用给定的值填充数组,直到数组达到指定的大小。该方法的行为与 array_pad PHP 函数功能类似。
要填充到左侧,你应该使用负值。如果给定大小的绝对值小于或等于数组的长度,则不会发生填充:
$collection = collect(['A', 'B', 'C']);
$filtered = $collection->pad(5, 0);
$filtered->all();
// ['A', 'B', 'C', 0, 0]
$filtered = $collection->pad(-5, 0);
$filtered->all();
// [0, 0, 'A', 'B', 'C']
partition()
partition
方法可以和 PHP 函数中的 list
结合使用,用来分开通过指定条件的元素以及那些不通过指定条件的元素:
$collection = collect([1, 2, 3, 4, 5, 6]);
list($underThree, $equalOrAboveThree) = $collection->partition(function ($i) {
return $i < 3;
});
$underThree->all();
// [1, 2]
$equalOrAboveThree->all();
// [3, 4, 5, 6]
pipe()
pipe
方法传入一个回调函数并返回结果:
$collection = collect([1, 2, 3]);
$piped = $collection->pipe(function ($collection) {
return $collection->sum();
});
// 6
pluck()
pluck
方法可以获取集合中指定键对应的所有值:
$collection = collect([
['product_id' => 'prod-100', 'name' => 'Desk'],
['product_id' => 'prod-200', 'name' => 'Chair'],
]);
$plucked = $collection->pluck('name');
$plucked->all();
// ['Desk', 'Chair']
你也可以通过传入第二个参数来指定生成集合的键:
$plucked = $collection->pluck('name', 'product_id');
$plucked->all();
// ['prod-100' => 'Desk', 'prod-200' => 'Chair']
如果存在重复的键,则最后一个匹配元素将被插入到弹出的集合中
$collection = collect([
['brand' => 'Tesla', 'color' => 'red'],
['brand' => 'Pagani', 'color' => 'white'],
['brand' => 'Tesla', 'color' => 'black'],
['brand' => 'Pagani', 'color' => 'orange'],
]);
$plucked = $collection->pluck('color', 'brand');
$plucked->all();
// ['Tesla' => 'black', 'Pagani' => 'orange']
pop()
pop
从原集合返回并移除最后一个集合项:
$collection = collect([1, 2, 3, 4, 5]);
$collection->pop();
// 5
$collection->all();
// [1, 2, 3, 4]
prepend()
prepend
方法将指定的值添加的集合的开头:
$collection = collect([1, 2, 3, 4, 5]);
$collection->prepend(0);
$collection->all();
// [0, 1, 2, 3, 4, 5]
你也可以传递第二个参数来设置新增加集合项的键:
$collection = collect(['one' => 1, 'two' => 2]);
$collection->prepend(0, 'zero');
$collection->all();
// ['zero' => 0, 'one' => 1, 'two' => 2]
pull()
pull
方法把指定键对应的值从集合中移除并返回:
$collection = collect(['product_id' => 'prod-100', 'name' => 'Desk']);
$collection->pull('name');
// 'Desk'
$collection->all();
// ['product_id' => 'prod-100']
push()
push
方法把指定的值追加到集合项的末尾:
$collection = collect([1, 2, 3, 4]);
$collection->push(5);
$collection->all();
// [1, 2, 3, 4, 5]
put()
put
方法在集合内设置给定的键值对:
$collection = collect(['product_id' => 1, 'name' => 'Desk']);
$collection->put('price', 100);
$collection->all();
// ['product_id' => 1, 'name' => 'Desk', 'price' => 100]
random()
random
方法从集合中返回一个随机项:
$collection = collect([1, 2, 3, 4, 5]);
$collection->random();
// 4 - (retrieved randomly)
你可以选择传入一个整数到 random
来指定要获取的随即项的数量。只要你显示传递你希望接收的数量时,则会返回项目的集合:
$random = $collection->random(3);
$random->all();
// [2, 4, 5] - (retrieved randomly)
如果集合的项小于指定的数量,则该方法将抛出 InvalidArgumentException
。
reduce()
reduce
方法将每次迭代的结果传递给下一次迭代直到集合减少为单个值:
$collection = collect([1, 2, 3]);
$total = $collection->reduce(function ($carry, $item) {
return $carry + $item;
});
// 6
第一次迭代时 $carry
的数值为 null
; however,你也可以通过传入第二个参数到 reduce
来指定它的初始值:
$collection->reduce(function ($carry, $item) {
return $carry + $item;
}, 4);
// 10
reject()
reject
方法使用指定的回调函数过滤集合。如果回调函数返回 true 就会把对应的集合项从集合中移除:
$collection = collect([1, 2, 3, 4]);
$filtered = $collection->reject(function ($value, $key) {
return $value > 2;
});
$filtered->all();
// [1, 2]
与 reject
方法对应的是 filter
方法。
replace()
replace
方法类似于 merge
;但是,不仅可以覆盖匹配到的相同字符串键的集合项,而且也可以覆盖数字键的集合项:
$collection = collect(['Taylor', 'Abigail', 'James']);
$replaced = $collection->replace([1 => 'Victoria', 3 => 'Finn']);
$replaced->all();
// ['Taylor', 'Victoria', 'James', 'Finn']
replaceRecursive()
这个方法类似 replace
,但是会以递归的形式将数组替换到具有相同键的集合项中:
$collection = collect(['Taylor', 'Abigail', ['James', 'Victoria', 'Finn']]);
$replaced = $collection->replaceRecursive(['Charlie', 2 => [1 => 'King']]);
$replaced->all();
// ['Charlie', 'Abigail', ['James', 'King', 'Finn']]
reverse()
reverse
方法用来倒转集合项的顺序,并保留原始的键:
$collection = collect(['a', 'b', 'c', 'd', 'e']);
$reversed = $collection->reverse();
$reversed->all();
/*
[
4 => 'e',
3 => 'd',
2 => 'c',
1 => 'b',
0 => 'a',
]
*/
search()
search
方法在集合中搜索给定的值并返回它的键。如果没有找到,则返回 false
。
$collection = collect([2, 4, 6, 8]);
$collection->search(4);
// 1
使用 「宽松」的方式进行搜索,这意味着具有整数值的字符串会被认为等于相同值的整数。使用 「严格」的方式进行搜索,就传入 true
作为该方法的第二个参数:
$collection->search('4', true);
// false
或者,你可以通过传递回调函数来搜索通过条件测试的第一个集合项:
$collection->search(function ($item, $key) {
return $item > 5;
});
// 2
shift()
shift
方法移除并返回集合的第一个集合项:
$collection = collect([1, 2, 3, 4, 5]);
$collection->shift();
// 1
$collection->all();
// [2, 3, 4, 5]
shuffle()
shuffle
方法随机打乱集合项:
$collection = collect([1, 2, 3, 4, 5]);
$shuffled = $collection->shuffle();
$shuffled->all();
// [3, 2, 5, 1, 4] - (generated randomly)
skip()
skip
方法返回除了给定的集合项数目的新集合:
$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
$collection = $collection->skip(4);
$collection->all();
// [5, 6, 7, 8, 9, 10]
slice()
slice
方法返回集合中给定索引开始后面的部分:
$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
$slice = $collection->slice(4);
$slice->all();
// [5, 6, 7, 8, 9, 10]
如果你想限制返回内容的大小,可以将你期望的大小作为第二个参数传递到该方法:
$slice = $collection->slice(4, 2);
$slice->all();
// [5, 6]
默认情况下,返回的内容将会保留原始键。如果你不希望保留原始键,你可以使用 values
方法来重新建立索引。
some()
contains
方法的别名。.
sort()
sort
方法对集合进行排序。排序后的集合会保留原数组的键,所以在这个例子我们将使用 values
方法去把键重置为连续编号的索引:
$collection = collect([5, 3, 1, 2, 4]);
$sorted = $collection->sort();
$sorted->values()->all();
// [1, 2, 3, 4, 5]
如果你有更高级的排序需求,可以通过自己的算法将回调函数传递到 sort
。请参阅 PHP 文档的 uasort
,这是集合的 sort
方法在底层所调用的。
技巧:如果你需要对嵌套数组或对象进行排序,请参照
sortBy
和sortByDesc
方法。
sortBy()
sortBy
方法将根据指定键对集合进行排序。排序后的集合会保留原始数组的键,所以在这个例子中我们使用 values
方法将键重置为连续编号的索引:
$collection = collect([
['name' => 'Desk', 'price' => 200],
['name' => 'Chair', 'price' => 100],
['name' => 'Bookcase', 'price' => 150],
]);
$sorted = $collection->sortBy('price');
$sorted->values()->all();
/*
[
['name' => 'Chair', 'price' => 100],
['name' => 'Bookcase', 'price' => 150],
['name' => 'Desk', 'price' => 200],
]
*/
你也可以传递你自己的回调函数用于决定如何对集合的值进行排序:
$collection = collect([
['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
['name' => 'Chair', 'colors' => ['Black']],
['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
]);
$sorted = $collection->sortBy(function ($product, $key) {
return count($product['colors']);
});
$sorted->values()->all();
/*
[
['name' => 'Chair', 'colors' => ['Black']],
['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
]
*/
sortByDesc()
该方法与 sortBy
方法一样,但是会以相反的顺序来对集合进行排序:
sortDesc()
该方法与 sort
方法一样,但是会以相反的顺序来对集合进行排序:
$collection = collect([5, 3, 1, 2, 4]);
$sorted = $collection->sortDesc();
$sorted->values()->all();
// [5, 4, 3, 2, 1]
sortKeys()
sortKeys
方法通过底层关联数组的键来对集合进行排序:
$collection = collect([
'id' => 22345,
'first' => 'John',
'last' => 'Doe',
]);
$sorted = $collection->sortKeys();
$sorted->all();
/*
[
'first' => 'John',
'id' => 22345,
'last' => 'Doe',
]
*/
sortKeysDesc()
该方法与 sortKeys
方法一样,但是会以相反的顺序来对集合进行排序。
splice()
splice
方法移除并返回指定索引开始的集合项片段:
$collection = collect([1, 2, 3, 4, 5]);
$chunk = $collection->splice(2);
$chunk->all();
// [3, 4, 5]
$collection->all();
// [1, 2]
你可以传递第二个参数用以限制被删除内容的大小:
$collection = collect([1, 2, 3, 4, 5]);
$chunk = $collection->splice(2, 1);
$chunk->all();
// [3]
$collection->all();
// [1, 2, 4, 5]
此外,你可以传入含有新参数项的第三个参数来代替集合中删除的集合项:
$collection = collect([1, 2, 3, 4, 5]);
$chunk = $collection->splice(2, 1, [10, 11]);
$chunk->all();
// [3]
$collection->all();
// [1, 2, 10, 11, 4, 5]
split()
split
方法将集合按照给定的值拆分:
$collection = collect([1, 2, 3, 4, 5]);
$groups = $collection->split(3);
$groups->toArray();
// [[1, 2], [3, 4], [5]]
sum()
sum
方法返回集合内所有项的和:
collect([1, 2, 3, 4, 5])->sum();
// 15
如果集合包含嵌套数组或对象,则应该传入一个键来指定要进行求和的值:
$collection = collect([
['name' => 'JavaScript: The Good Parts', 'pages' => 176],
['name' => 'JavaScript: The Definitive Guide', 'pages' => 1096],
]);
$collection->sum('pages');
// 1272
另外,你可以传入自己的回调函数来决定要用集合中的哪些值进行求和:
$collection = collect([
['name' => 'Chair', 'colors' => ['Black']],
['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
]);
$collection->sum(function ($product) {
return count($product['colors']);
});
// 6
take()
take
方法返回给定数量项的新集合:
$collection = collect([0, 1, 2, 3, 4, 5]);
$chunk = $collection->take(3);
$chunk->all();
// [0, 1, 2]
你也可以传递负整数从集合末尾获取指定数量的项:
$collection = collect([0, 1, 2, 3, 4, 5]);
$chunk = $collection->take(-2);
$chunk->all();
// [4, 5]
tap()
tap
方法将给定的回调函数传入该集合,允许你在一个特定点「tap」集合,并在不影响集合本身的情况下对集合项执行某些操作:
collect([2, 4, 3, 1, 5])
->sort()
->tap(function ($collection) {
Log::debug('Values after sorting', $collection->values()->toArray());
})
->shift();
// 1
times()
静态 times
方法通过调用给定次数的回调函数来创建新集合:
$collection = Collection::times(10, function ($number) {
return $number * 9;
});
$collection->all();
// [9, 18, 27, 36, 45, 54, 63, 72, 81, 90]
使用这个方法可以与工厂结合使用创建出 Eloquent 模型:
$categories = Collection::times(3, function ($number) {
return factory(Category::class)->create(['name' => "Category No. $number"]);
});
$categories->all();
/*
[
['id' => 1, 'name' => 'Category No. 1'],
['id' => 2, 'name' => 'Category No. 2'],
['id' => 3, 'name' => 'Category No. 3'],
]
*/
toArray()
toArray
方法将集合转换成 PHP array
。如果集合的值是 Eloquent 模型,那也会被转换成数组:
$collection = collect(['name' => 'Desk', 'price' => 200]);
$collection->toArray();
/*
[
['name' => 'Desk', 'price' => 200],
]
*/
注意:
toArray
也会将所有集合的嵌套对象转换为数组。如果你想获取原数组,可以使用all
方法。
toJson()
toJson
方法将集合转换成 JSON 字符串:
$collection = collect(['name' => 'Desk', 'price' => 200]);
$collection->toJson();
// '{"name":"Desk", "price":200}'
transform()
transform
方法会遍历整个集合,并对集合中的每项都会调用其回调函数。集合中的值将被替换为回调函数返回的值:
$collection = collect([1, 2, 3, 4, 5]);
$collection->transform(function ($item, $key) {
return $item * 2;
});
$collection->all();
// [2, 4, 6, 8, 10]
注意:与大多数集合方法不同,
transform
会修改集合本身。如果你想创建新集合,可以使用map
方法。
union()
union
方法将给定数组添加到集合中。如果给定的数组含有与原集合一样的键,则首选原始集合的值:
$collection = collect([1 => ['a'], 2 => ['b']]);
$union = $collection->union([3 => ['c'], 1 => ['b']]);
$union->all();
// [1 => ['a'], 2 => ['b'], 3 => ['c']]
unique()
unique
方法返回集合中所有唯一项。返回的集合保留着原数组的键,所以在这个例子中,我们使用 values
方法把键重置为连续编号的索引:
$collection = collect([1, 1, 2, 2, 3, 4, 2]);
$unique = $collection->unique();
$unique->values()->all();
// [1, 2, 3, 4]
当处理嵌套数组或对象时,你可以指定用于确定唯一性的键:
$collection = collect([
['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'],
['name' => 'iPhone 5', 'brand' => 'Apple', 'type' => 'phone'],
['name' => 'Apple Watch', 'brand' => 'Apple', 'type' => 'watch'],
['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'],
['name' => 'Galaxy Gear', 'brand' => 'Samsung', 'type' => 'watch'],
]);
$unique = $collection->unique('brand');
$unique->values()->all();
/*
[
['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'],
['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'],
]
*/
你也可以通过传递自己的回调函数来确定对象的唯一性:
$unique = $collection->unique(function ($item) {
return $item['brand'].$item['type'];
});
$unique->values()->all();
/*
[
['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'],
['name' => 'Apple Watch', 'brand' => 'Apple', 'type' => 'watch'],
['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'],
['name' => 'Galaxy Gear', 'brand' => 'Samsung', 'type' => 'watch'],
]
*/
unique
方法在检查项目值时使用「宽松」模式比较,意味着具有整数值的字符串将被视为等于相同值的整数。你可以使用 uniqueStrict
方法做「严格」模式比较。
技巧:这个方法的行为在使用 Eloquent Collections 时被修改。
uniqueStrict()
这个方法与 unique
方法一样,然而,所有的值是用 「严格」模式来比较的。
unless()
unless
法当传入的第一个参数不为 true
的时候,将执行给定的回调函数:
$collection = collect([1, 2, 3]);
$collection->unless(true, function ($collection) {
return $collection->push(4);
});
$collection->unless(false, function ($collection) {
return $collection->push(5);
});
$collection->all();
// [1, 2, 3, 5]
与 unless
相反的方法, 请查看 when
方法。
unlessEmpty()
whenNotEmpty
的别名方法。
unlessNotEmpty()
whenEmpty
的别名方法。
unwrap()
静态 unwrap
方法返回集合内部的可用值:
Collection::unwrap(collect('John Doe'));
// ['John Doe']
Collection::unwrap(['John Doe']);
// ['John Doe']
Collection::unwrap('John Doe');
// 'John Doe'
values()
values
方法返回键被重置为连续编号的新集合:
$collection = collect([
10 => ['product' => 'Desk', 'price' => 200],
11 => ['product' => 'Desk', 'price' => 200]
]);
$values = $collection->values();
$values->all();
/*
[
0 => ['product' => 'Desk', 'price' => 200],
1 => ['product' => 'Desk', 'price' => 200],
]
*/
when()
当 when
方法的第一个参数传入为 true
时,将执行给定的回调函数:
$collection = collect([1, 2, 3]);
$collection->when(true, function ($collection) {
return $collection->push(4);
});
$collection->when(false, function ($collection) {
return $collection->push(5);
});
$collection->all();
// [1, 2, 3, 4]
与 when
相反的方法, 请查看 unless
。
whenEmpty()
whenEmpty
方法是当集合为空时,将执行给定的回调函数:
$collection = collect(['michael', 'tom']);
$collection->whenEmpty(function ($collection) {
return $collection->push('adam');
});
$collection->all();
// ['michael', 'tom']
$collection = collect();
$collection->whenEmpty(function ($collection) {
return $collection->push('adam');
});
$collection->all();
// ['adam']
$collection = collect(['michael', 'tom']);
$collection->whenEmpty(function ($collection) {
return $collection->push('adam');
}, function ($collection) {
return $collection->push('taylor');
});
$collection->all();
// ['michael', 'tom', 'taylor']
与 whenEmpty
相反的方法, 请查看whenNotEmpty
。
whenNotEmpty()
whenNotEmpty
方法当集合不为空时,将执行给定的回调函数:
$collection = collect(['michael', 'tom']);
$collection->whenNotEmpty(function ($collection) {
return $collection->push('adam');
});
$collection->all();
// ['michael', 'tom', 'adam']
$collection = collect();
$collection->whenNotEmpty(function ($collection) {
return $collection->push('adam');
});
$collection->all();
// []
$collection = collect();
$collection->whenNotEmpty(function ($collection) {
return $collection->push('adam');
}, function ($collection) {
return $collection->push('taylor');
});
$collection->all();
// ['taylor']
与 whenNotEmpty
相反的方法,请查看 whenEmpty
。
where()
where
方法通过给定的键 / 值对查询过滤集合的结果:
$collection = collect([
['product' => 'Desk', 'price' => 200],
['product' => 'Chair', 'price' => 100],
['product' => 'Bookcase', 'price' => 150],
['product' => 'Door', 'price' => 100],
]);
$filtered = $collection->where('price', 100);
$filtered->all();
/*
[
['product' => 'Chair', 'price' => 100],
['product' => 'Door', 'price' => 100],
]
*/
where
方法在检查集合项值时使用「宽松」模式比较,这意味着具有整数值的字符串会被认为等于相同值的整数。你可以使用 whereStrict
方法进行「严格」模式比较。
而且,你还可以将一个比较运算符作为第二个参数传递。
$collection = collect([
['name' => 'Jim', 'deleted_at' => '2019-01-01 00:00:00'],
['name' => 'Sally', 'deleted_at' => '2019-01-02 00:00:00'],
['name' => 'Sue', 'deleted_at' => null],
]);
$filtered = $collection->where('deleted_at', '!=', null);
$filtered->all();
/*
[
['name' => 'Jim', 'deleted_at' => '2019-01-01 00:00:00'],
['name' => 'Sally', 'deleted_at' => '2019-01-02 00:00:00'],
]
*/
whereStrict()
此方法和 where
方法使用相似;但是它是「严格」模式去匹配值和类型。
whereBetween()
whereBetween
方法会筛选给定范围的集合:
$collection = collect([
['product' => 'Desk', 'price' => 200],
['product' => 'Chair', 'price' => 80],
['product' => 'Bookcase', 'price' => 150],
['product' => 'Pencil', 'price' => 30],
['product' => 'Door', 'price' => 100],
]);
$filtered = $collection->whereBetween('price', [100, 200]);
$filtered->all();
/*
[
['product' => 'Desk', 'price' => 200],
['product' => 'Bookcase', 'price' => 150],
['product' => 'Door', 'price' => 100],
]
*/
whereIn()
whereIn
方法会根据包含给定数组的键 / 值对来过滤集合:
$collection = collect([
['product' => 'Desk', 'price' => 200],
['product' => 'Chair', 'price' => 100],
['product' => 'Bookcase', 'price' => 150],
['product' => 'Door', 'price' => 100],
]);
$filtered = $collection->whereIn('price', [150, 200]);
$filtered->all();
/*
[
['product' => 'Desk', 'price' => 200],
['product' => 'Bookcase', 'price' => 150],
]
*/
whereIn
方法在检查集合项值时使用「宽松」模式比较,这意味着具有整数值的字符串会被认为等于相同值的整数。你可以使用 whereInStrict
方法进行「严格」模式比较。
whereInStrict()
此方法和 whereIn
方法使用相似;但是它是「严格」模式去匹配值和类型。
whereInstanceOf()
whereInstanceOf
方法根据给定的类来过滤集合:
use App\User;
use App\Post;
$collection = collect([
new User,
new User,
new Post,
]);
$filtered = $collection->whereInstanceOf(User::class);
$filtered->all();
// [App\User, App\User]
whereNotBetween()
whereNotBetween
方法在指定的范围内过滤集合:
$collection = collect([
['product' => 'Desk', 'price' => 200],
['product' => 'Chair', 'price' => 80],
['product' => 'Bookcase', 'price' => 150],
['product' => 'Pencil', 'price' => 30],
['product' => 'Door', 'price' => 100],
]);
$filtered = $collection->whereNotBetween('price', [100, 200]);
$filtered->all();
/*
[
['product' => 'Chair', 'price' => 80],
['product' => 'Pencil', 'price' => 30],
]
*/
whereNotIn()
whereNotIn
方法根据未包含在指定数组的键 / 值对来对集合进行过滤:
$collection = collect([
['product' => 'Desk', 'price' => 200],
['product' => 'Chair', 'price' => 100],
['product' => 'Bookcase', 'price' => 150],
['product' => 'Door', 'price' => 100],
]);
$filtered = $collection->whereNotIn('price', [150, 200]);
$filtered->all();
/*
[
['product' => 'Chair', 'price' => 100],
['product' => 'Door', 'price' => 100],
]
*/
whereNotIn
方法在检查集合项值时使用「宽松」模式比较,这意味着具有整数值的字符串会被认为等于相同值的整数。你可以使用 whereNotInStrict
方法进行「严格」模式比较。
whereNotInStrict()
这个方法与 whereNotIn
方法类似;不同的是会使用「严格」模式比较。
whereNotNull()
whereNotNull
方法筛选给定键不为 NULL 的项:
$collection = collect([
['name' => 'Desk'],
['name' => null],
['name' => 'Bookcase'],
]);
$filtered = $collection->whereNotNull('name');
$filtered->all();
/*
[
['name' => 'Desk'],
['name' => 'Bookcase'],
]
*/
whereNull()
whereNull
方法筛选给定键不为 NULL 的项:
$collection = collect([
['name' => 'Desk'],
['name' => null],
['name' => 'Bookcase'],
]);
$filtered = $collection->whereNull('name');
$filtered->all();
/*
[
['name' => null],
]
*/
wrap()
静态 wrap
方法在适当的情况下将指定的值放在集合中:
$collection = Collection::wrap('John Doe');
$collection->all();
// ['John Doe']
$collection = Collection::wrap(['John Doe']);
$collection->all();
// ['John Doe']
$collection = Collection::wrap(collect('John Doe'));
$collection->all();
// ['John Doe']
zip()
zip
方法将指定数组的值和相应索引的原集合的值合并在一起:
$collection = collect(['Chair', 'Desk']);
$zipped = $collection->zip([100, 200]);
$zipped->all();
// [['Chair', 100], ['Desk', 200]]
高阶消息传递
集合也提供对「高阶消息传递」的支持,即集合常见操作的快捷方式。支持高阶消息传递的集合方法有: average
, avg
, contains
, each
, every
, filter
, first
, flatMap
, groupBy
, keyBy
, map
, max
, min
, partition
, reject
, some
, sortBy
, sortByDesc
, sum
, 和 unique
.。
每个高阶消息传递都能作为集合实例的动态的属性来访问。例如,使用 each
高阶消息传递在集合中的每个对象上调用一个方法:
$users = User::where('votes', '>', 500)->get();
$users->each->markAsVip();
同样,我们可以使用 sum
高阶消息传递来收集 users 集合中的「投票」总数:
$users = User::where('group', 'Development')->get();
return $users->sum->votes;
懒集合
简介
注意:注意:在进一步学习 Laravel 的懒集合之前,我们先花点时间熟悉一下 PHP generators.
为了补充已经很强大的 Collection
类, LazyCollection
类利用了 PHP 的 generators 来允许你在保持低内存使用率的同时使用非常大的数据集。
例如,假设你的应用需要处理一个千兆字节的日志文件,同时利用 Laravel 的集合方法来解析这个日志文件。与其一次将整个文件读入内存,不如使用懒集合在给定时间仅将文件的一小部分保留在内存中:
use App\LogEntry;
use Illuminate\Support\LazyCollection;
LazyCollection::make(function () {
$handle = fopen('log.txt', 'r');
while (($line = fgets($handle)) !== false) {
yield $line;
}
})->chunk(4)->map(function ($lines) {
return LogEntry::fromLines($lines);
})->each(function (LogEntry $logEntry) {
// Process the log entry...
});
或者,假设你需要遍历 10000 个 Eloquent 模型。当使用传统的 Laravel 集合时,全部 10000 个 Eloquent 模型必须同时加载到内存中:
$users = App\User::all()->filter(function ($user) {
return $user->id > 500;
});
然而,查询构建器的 cursor
方法返回一个 LazyCollection
实例。这允许你对数据库只进行一次查询, 而且一次只能在内存中加载一个 Eloquent 模型。在此例中, filter
回调只有在我们实际逐个迭代每个用户之后才会执行,这样可以大幅度减少内存使用:
$users = App\User::cursor()->filter(function ($user) {
return $user->id > 500;
});
foreach ($users as $user) {
echo $user->id;
}
懒集合
要创建一个懒集合实例,你应该将 PHP 生成器函数传递给懒集合的 make
方法:
use Illuminate\Support\LazyCollection;
LazyCollection::make(function () {
$handle = fopen('log.txt', 'r');
while (($line = fgets($handle)) !== false) {
yield $line;
}
});
The Enumerable Contract
Collection
类中几乎所有的方法在 LazyCollection
类中也能使用。这两个类都实现了 Illuminate\Support\Enumerable
契约,该契约定义了以下方法:
all average avg chunk collapse collect combine concat contains containsStrict count countBy crossJoin dd diff diffAssoc diffKeys dump duplicates duplicatesStrict each eachSpread every except filter first firstWhere flatMap flatten flip forPage get groupBy has implode intersect intersectByKeys isEmpty isNotEmpty join keyBy keys last macro make map mapInto mapSpread mapToGroups mapWithKeys max median merge mergeRecursive min mode nth only pad partition pipe pluck random reduce reject replace replaceRecursive reverse search shuffle skip slice some sort sortBy sortByDesc sortKeys sortKeysDesc split sum take tap times toArray toJson union unique uniqueStrict unless unlessEmpty unlessNotEmpty unwrap values when whenEmpty whenNotEmpty where whereStrict whereBetween whereIn whereInStrict whereInstanceOf whereNotBetween whereNotIn whereNotInStrict wrap zip
注意
LazyCollection
类不提供使集合变动的方法(如shift
,pop
,prepend
等)。
懒集合方法
除了在 Enumerable
契约中定义的方法外,LazyCollection
类还包含以下方法:
tapEach()
当 each
方法为集合中每一个集合项调用给定回调时,tapEach
方法仅调用给定回调,因为这些集合项正在逐个从列表中拉出:
$lazyCollection = LazyCollection::times(INF)->tapEach(function ($value) {
dump($value);
});
// Nothing has been dumped so far...
$array = $lazyCollection->take(3)->all();
// 1
// 2
// 3
remember()
remember
方法返回一个新的懒集合,这个集合已经记住了(缓存)已枚举所有的值,当再次枚举该集合时不会检索它们:
$users = User::cursor()->remember();
// 没执行任何查询
$users->take(5)->all();
// 执行了查询操作,并且前 5 个用户数据已经在数据库中查询完成
$users->take(20)->all();
// 前 5 个用户数据在缓存中获取,其余 15 个用户数据在数据库中查询
本文章首发在 LearnKu.com 网站上。
本文中的所有译文仅用于学习和交流目的,转载请务必注明文章译者、出处、和本文链接 我们的翻译工作遵照 CC 协议,如果我们的工作有侵犯到您的权益,请及时联系我们。
Laravel China 社区:https://learnku.com/docs/laravel/7.x/collections/7483