IlluminateSupportCollection クラスは、配列データを処理するためのスムーズで便利なカプセル化を提供します。たとえば、以下のコードを見てください。ヘルパー関数collectを使用して新しいコレクションインスタンスを作成し、要素ごとにstrtoupper関数を実行して、空の要素をすべて削除します。
$collection = collect(['taylor', 'abigail', null])->map(function ($name) { return strtoupper($name); })->reject(function ($name) { return empty($name); });
ご覧のとおり、Collectionクラスでは次のことが可能です。メソッドを使用するには チェーンは、基になる配列に対してマッチング操作とリダクション操作を実行します。通常、各 Collection メソッドは新しい Collection インスタンスを返します。
前述のように、ヘルパー関数collectは指定された配列の新しいIlluminateSupportCollectionインスタンスを返すため、コレクションの作成は簡単です:
$collection = collect([1, 2, 3]);
デフォルトでは、Eloquentモデルのコレクションは常にCollectionインスタンスを返します。 , また、Collection クラスは、メソッドがどこで使用されるかぎり、自由に使用できます。
このドキュメントの次の部分では、メソッド チェーン内の基になる配列をスムーズに操作できる、Collection クラスのすべての有効なメソッドについて説明します。さらに、ほぼすべてのメソッドは新しい Collection インスタンスを返すため、必要に応じて元のコレクションのコピーを保持できます。
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 メソッドは、多次元配列コレクションを 1 次元配列に折りたたみます。配列:
$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]
各メソッドはコレクション内のデータ項目を反復し、各データ項目を指定されたコールバックに渡します:
$collection = $collection->each(function ($item, $key) { //});
コールバックから false を返すとループが終了します:
$collection = $collection->each(function ($item, $key) { if (/* some condition */) { return false; }});
each メソッド 配列の 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 の反対が唯一のメソッドです。
$collection = collect([1, 2, 3, 4]);$filtered = $collection->filter(function ($item) { return $item > 2;});$filtered->all();// [3, 4]
first()
collect([1, 2, 3, 4])->first(function ($key, $value) { return $value > 2;});// 3
collect([1, 2, 3, 4])->first();// 1
$collection = collect(['name' => 'taylor', 'languages' => ['php', 'javascript']]);$flattened = $collection->flatten();$flattened->all();// ['taylor', 'php', 'javascript'];
$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);$flipped = $collection->flip();$flipped->all();// ['taylor' => 'name', 'laravel' => 'framework']
$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])->forPage(2, 3);$collection->all();// [4, 5, 6]
get()
$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
$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'], ],]*/
$collection = collect(['account_id' => 1, 'product' => 'Desk']);$collection->has('email');// false
コレクションに配列またはオブジェクトが含まれている場合は、結合したいプロパティ キーと、値の間に入れる「接着剤」文字列を渡す必要があります。
$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方法返回 true;否则返回 false:
collect([])->isEmpty();// true
将指定键的值作为集合的键:
$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方法返回所有集合的键:
$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方法返回通过测试的集合的最后一个元素:
collect([1, 2, 3, 4])->last(function ($key, $value) { return $value < 3;});// 2
还可以调用无参的 last方法来获取集合的最后一个元素。如果集合为空。返回 null:
collect([1, 2, 3, 4])->last();// 4
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方法。
max方法返回集合中最大值:
$max = collect([['foo' => 10], ['foo' => 20]])->max('foo');// 20$max = collect([1, 2, 3, 4, 5])->max();// 5
merge方法合并给定数组到集合。该数组中的任何字符串键匹配集合中的字符串键的将会重写集合中的值:
$collection = collect(['product_id' => 1, 'name' => 'Desk']);$merged = $collection->merge(['price' => 100, 'discount' => false]);$merged->all();// ['product_id' => 1, 'name' => 'Desk', 'price' => 100, 'discount' => false]
如果给定数组的键是数字,数组的值将会附加到集合后面:
$collection = collect(['Desk', 'Chair']);$merged = $collection->merge(['Bookcase', 'Door']);$merged->all();// ['Desk', 'Chair', 'Bookcase', 'Door']
min方法返回集合中的最小值:
$min = collect([['foo' => 10], ['foo' => 20]])->min('foo');// 10$min = collect([1, 2, 3, 4, 5])->min();// 1
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 方法。
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']
pop方法移除并返回集合中最后面的数据项:
$collection = collect([1, 2, 3, 4, 5]);$collection->pop();// 5$collection->all();// [1, 2, 3, 4]
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方法通过键从集合中移除并返回数据项:
$collection = collect(['product_id' => 'prod-100', 'name' => 'Desk']);$collection->pull('name');// 'Desk'$collection->all();// ['product_id' => 'prod-100']
push方法附加数据项到集合结尾:
$collection = collect([1, 2, 3, 4]);$collection->push(5);$collection->all();// [1, 2, 3, 4, 5]
put方法在集合中设置给定键和值:
$collection = collect(['product_id' => 1, 'name' => 'Desk']);$collection->put('price', 100);$collection->all();// ['product_id' => 1, 'name' => 'Desk', 'price' => 100]
random方法从集合中返回随机数据项:
$collection = collect([1, 2, 3, 4, 5]);$collection->random();// 4 - (retrieved randomly)
你可以传递一个整型数据到 random函数,如果该整型数值大于1,将会返回一个集合:
$random = $collection->random(3);$random->all();// [2, 4, 5] - (retrieved randomly)
reduce方法用于减少集合到单个值,传递每个迭代结果到随后的迭代:
$collection = collect([1, 2, 3]);$total = $collection->reduce(function ($carry, $item) { return $carry + $item;});// 6
在第一次迭代时 $carry的值是null;然而,你可以通过传递第二个参数到 reduce来指定其初始值:
$collection->reduce(function ($carry, $item) { return $carry + $item;}, 4);// 10
reject方法使用给定回调过滤集合,该回调应该为所有它想要从结果集合中移除的数据项返回 true:
$collection = collect([1, 2, 3, 4]);$filtered = $collection->reject(function ($item) { return $item > 2;});$filtered->all();// [1, 2]
和 reduce方法相对的方法是filter方法。
reverse方法将集合数据项的顺序颠倒:
$collection = collect([1, 2, 3, 4, 5]);$reversed = $collection->reverse();$reversed->all();// [5, 4, 3, 2, 1]
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方法从集合中移除并返回第一个数据项:
$collection = collect([1, 2, 3, 4, 5]);$collection->shift();// 1$collection->all();// [2, 3, 4, 5]
shuffle方法随机打乱集合中的数据项:
$collection = collect([1, 2, 3, 4, 5]);$shuffled = $collection->shuffle();$shuffled->all();// [3, 2, 5, 1, 4] // (generated randomly)
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]
返回的切片有新的、数字化索引的键,如果你想要保持原有的键,可以传递第三个参数 true到该方法。
sort方法对集合进行排序:
$collection = collect([5, 3, 1, 2, 4]);$sorted = $collection->sort();$sorted->values()->all();// [1, 2, 3, 4, 5]
排序后的集合保持原来的数组键,在本例中我们使用 values 方法重置键为连续编号索引。
要为嵌套集合和对象排序,查看 sortBy和 sortByDesc方法。
如果你需要更加高级的排序,你可以使用自己的算法传递一个回调给 sort方法。参考 PHP 官方文档关于 usort 的说明, sort方法底层正是调用了该方法。
sortBy方法通过给定键对集合进行排序:
$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], ]*/
排序后的集合保持原有数组索引,在本例中,使用 values方法重置键为连续索引。
你还可以传递自己的回调来判断如何排序集合的值:
$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']], ]*/
该方法和 sortBy用法相同,不同之处在于按照相反顺序进行排序。
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]
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方法使用指定数目的数据项返回一个新的集合:
$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]
toArray方法将集合转化为一个原生的 PHP 数组。如果集合的值是Eloquent 模型,该模型也会被转化为数组:
$collection = collect(['name' => 'Desk', 'price' => 200]);$collection->toArray();/* [ ['name' => 'Desk', 'price' => 200], ]*/
注意: toArray还将所有嵌套对象转化为数组。如果你想要获取底层数组,使用 all方法。
toJson方法将集合转化为JSON:
$collection = collect(['name' => 'Desk', 'price' => 200]);$collection->toJson();// '{"name":"Desk","price":200}'
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方法。
unique方法返回集合中所有的唯一数据项:
$collection = collect([1, 1, 2, 2, 3, 4, 2]);$unique = $collection->unique();$unique->values()->all();// [1, 2, 3, 4]
返回的集合保持原来的数组键,在本例中我们使用values方法重置这些键为连续的数字索引。
处理嵌套数组或对象时,可以指定用于判断唯一的键:
$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'], ]*/
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], ]*/
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方法使用严格条件约束。使用whereLoose方法过滤松散约束。
该方法和 where使用方法相同,不同之处在于 whereLoose在比较值的时候使用松散约束。
zip方法在于集合的值相应的索引处合并给定数组的值:
$collection = collect(['Chair', 'Desk']);$zipped = $collection->zip([100, 200]);$zipped->all();// [['Chair', 100], ['Desk', 200]]