さらに深く掘り下げる - コレクション（Collections） - 《Laravel 11.x ドキュメント》日本語

はじめに
- コレクションの作成
- コレクションの拡張
  - マクロ引数
利用可能なメソッド
メソッドリスト
Higher Order Messages
Lazy Collections

はじめに

Illuminate\Support\Collection クラスは、データの配列を操作するための流暢で便利なラッパーを提供します。例えば、次のコードを見てみましょう。collect ヘルパーを使用して配列から新しいコレクションインスタンスを作成し、各要素に strtoupper 関数を実行し、その後すべての空の要素を削除します:

$collection = collect(['taylor', 'abigail', null])->map(function (?string $name) {
   return strtoupper($name);
})->reject(function (string $name) {
   return empty($name);
});

ご覧の通り、Collection クラスは、そのメソッドをチェーンして基礎となる配列の流暢なマッピングと削減を行うことを可能にします。一般的に、コレクションは不変であり、すべての Collection メソッドはまったく新しい Collection インスタンスを返します。

コレクションの作成

上記のように、collect ヘルパーは指定された配列の新しい Illuminate\Support\Collection インスタンスを返します。したがって、コレクションを作成するのは非常に簡単です:

$collection = collect([1, 2, 3]);

Eloquent クエリの結果は常に Collection インスタンスとして返されます。

コレクションの拡張

コレクションは「マクロ可能」であり、実行時に Collection クラスに追加のメソッドを追加することができます。Illuminate\Support\Collection クラスの macro メソッドは、マクロが呼び出されたときに実行されるクロージャを受け入れます。マクロクロージャは、$this を介してコレクションの他のメソッドにアクセスできます。これは、コレクションクラスの実際のメソッドであるかのように扱われます。例えば、次のコードは toUpper メソッドを Collection クラスに追加します:

use Illuminate\Support\Collection;
use Illuminate\Support\Str;
Collection::macro('toUpper', function () {
   return $this->map(function (string $value) {
   return Str::upper($value);
   });
});
$collection = collect(['first', 'second']);
$upper = $collection->toUpper();
// ['FIRST', 'SECOND']

通常、コレクションマクロはサービスプロバイダーの boot メソッドで宣言するべきです。

マクロ引数

必要に応じて、追加の引数を受け入れるマクロを定義できます:

use Illuminate\Support\Collection;
use Illuminate\Support\Facades\Lang;
Collection::macro('toLocale', function (string $locale) {
   return $this->map(function (string $value) use ($locale) {
   return Lang::get($value, [], $locale);
   });
});
$collection = collect(['first', 'second']);
$translated = $collection->toLocale('es');

利用可能なメソッド

残りのコレクションドキュメントの大部分では、Collection クラスで利用可能な各メソッドについて説明します。これらのメソッドはすべて、基礎となる配列を流暢に操作するためにチェーンできます。さらに、ほとんどすべてのメソッドは新しい Collection インスタンスを返し、必要に応じてコレクションの元のコピーを保持できます:

after all average avg before chunk chunkWhile collapse collect combine concat contains containsOneItem containsStrict count countBy crossJoin dd diff diffAssoc diffAssocUsing diffKeys doesntContain dot dump duplicates duplicatesStrict each eachSpread ensure every except filter first firstOrFail firstWhere flatMap flatten flip forget forPage get groupBy has hasAny implode intersect intersectAssoc intersectByKeys isEmpty isNotEmpty join keyBy keys last lazy macro make map mapInto mapSpread mapToGroups mapWithKeys max median merge mergeRecursive min mode multiply nth only pad partition percentage pipe pipeInto pipeThrough pluck pop prepend pull push put random range reduce reduceSpread reject replace replaceRecursive reverse search select shift shuffle skip skipUntil skipWhile slice sliding sole some sort sortBy sortByDesc sortDesc sortKeys sortKeysDesc sortKeysUsing splice split splitIn sum take takeUntil takeWhile tap times toArray toJson transform undot union unique uniqueStrict unless unlessEmpty unlessNotEmpty unwrap value values when whenEmpty whenNotEmpty where whereStrict whereBetween whereIn whereInStrict whereInstanceOf whereNotBetween whereNotIn whereNotInStrict whereNotNull whereNull wrap zip

メソッドリスト

after()

after メソッドは、指定されたアイテムの後のアイテムを返します。指定されたアイテムが見つからない場合や最後のアイテムである場合は null が返されます:

$collection = collect([1, 2, 3, 4, 5]);
$collection->after(3);
// 4
$collection->after(5);
// null

このメソッドは「緩い」比較を使用して指定されたアイテムを検索します。つまり、整数値を含む文字列は同じ値の整数と等しいと見なされます。「厳密」比較を使用するには、strict 引数をメソッドに提供できます:

collect([2, 4, 6, 8])->after('4', strict: true);
// null

または、指定された真実テストを通過する最初のアイテムを検索するために独自のクロージャを提供できます:

collect([2, 4, 6, 8])->after(function (int $item, int $key) {
   return $item > 5;
});
// 8

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

before()

before メソッドは、after メソッドの逆です。指定されたアイテムの前のアイテムを返します。指定されたアイテムが見つからない場合や最初のアイテムである場合は null が返されます:

$collection = collect([1, 2, 3, 4, 5]);
$collection->before(3);
// 2
$collection->before(1);
// null
collect([2, 4, 6, 8])->before('4', strict: true);
// null
collect([2, 4, 6, 8])->before(function (int $item, int $key) {
   return $item > 5;
});
// 4

chunk()

chunk メソッドは、コレクションを指定されたサイズの複数の小さなコレクションに分割します:

$collection = collect([1, 2, 3, 4, 5, 6, 7]);
$chunks = $collection->chunk(4);
$chunks->all();
// [[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

chunkWhile()

chunkWhile メソッドは、指定されたコールバックの評価に基づいてコレクションを複数の小さなコレクションに分割します。クロージャに渡される $chunk 変数は、前の要素を検査するために使用できます:

$collection = collect(str_split('AABBCCCD'));
$chunks = $collection->chunkWhile(function (string $value, int $key, Collection $chunk) {
   return $value === $chunk->last();
});
$chunks->all();
// [['A', 'A'], ['B', 'B'], ['C', 'C', 'C'], ['D']]

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]

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();
$collection::class;
// 'Illuminate\Support\Collection'
$collection->all();
// [1, 2, 3]

collect メソッドは、Enumerable のインスタンスを持ち、非遅延コレクションインスタンスが必要な場合に特に便利です。collect() は Enumerable コントラクトの一部であるため、Collection インスタンスを取得するために安全に使用できます。

combine()

combine メソッドは、コレクションの値をキーとして、別の配列またはコレクションの値と組み合わせます:

$collection = collect(['name', 'age']);
$combined = $collection->combine(['George', 29]);
$combined->all();
// ['name' => 'George', 'age' => 29]

concat()

concat メソッドは、指定された array またはコレクションの値を別のコレクションの末尾に追加します:

$collection = collect(['John Doe']);
$concatenated = $collection->concat(['Jane Doe'])->concat(['name' => 'Johnny Doe']);
$concatenated->all();
// ['John Doe', 'Jane Doe', 'Johnny Doe']

concat メソッドは、元のコレクションに追加されたアイテムのキーを数値的に再インデックスします。連想コレクションのキーを保持するには、merge メソッドを参照してください。

contains()

contains メソッドは、コレクションが指定されたアイテムを含むかどうかを判断します。指定された真実テストに一致する要素がコレクションに存在するかどうかを判断するために、contains メソッドにクロージャを渡すことができます:

$collection = collect([1, 2, 3, 4, 5]);
$collection->contains(function (int $value, int $key) {
   return $value > 5;
});
// false

また、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 メソッドは、アイテム値をチェックする際に「緩い」比較を使用します。つまり、整数値を持つ文字列は同じ値の整数と等しいと見なされます。containsStrict メソッドを使用して「厳密」比較を使用してフィルタリングします。

contains の逆については、doesntContain メソッドを参照してください。

containsOneItem()

containsOneItem メソッドは、コレクションが単一のアイテムを含むかどうかを判断します:

collect([])->containsOneItem();
// false
collect(['1'])->containsOneItem();
// true
collect(['1', '2'])->containsOneItem();
// false

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(['', '', '']);
$counted = $collection->countBy(function (string $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 array と比較し、その値に基づいています。このメソッドは、指定されたコレクションに存在しない元のコレクションの値を返します:

$collection = collect([1, 2, 3, 4, 5]);
$diff = $collection->diff([2, 4, 6, 8]);
$diff->all();
// [1, 3, 5]

このメソッドの動作は、Eloquent Collections を使用する際に変更されます。

diffAssoc()

diffAssoc メソッドは、コレクションを別のコレクションまたはプレーンな PHP array と比較し、そのキーと値に基づいています。このメソッドは、指定されたコレクションに存在しない元のコレクションのキー/値ペアを返します:

$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]

diffAssocUsing()

diffAssoc とは異なり、diffAssocUsing はインデックス比較のためにユーザー提供のコールバック関数を受け入れます:

$collection = collect([
   'color' => 'orange',
   'type' => 'fruit',
   'remain' => 6,
]);
$diff = $collection->diffAssocUsing([
   'Color' => 'yellow',
   'Type' => 'fruit',
   'Remain' => 3,
], 'strnatcasecmp');
$diff->all();
// ['color' => 'orange', 'remain' => 6]

コールバックは、ゼロ未満、ゼロ、またはゼロより大きい整数を返す比較関数でなければなりません。詳細については、array_diff_uassoc に関する PHP ドキュメントを参照してください。これは、diffAssocUsing メソッドが内部で利用する PHP 関数です。

diffKeys()

diffKeys メソッドは、コレクションを別のコレクションまたはプレーンな PHP array と比較し、そのキーに基づいています。このメソッドは、指定されたコレクションに存在しない元のコレクションのキー/値ペアを返します:

$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]

doesntContain()

doesntContain メソッドは、コレクションが指定されたアイテムを含まないかどうかを判断します。指定された真実テストに一致しない要素がコレクションに存在するかどうかを判断するために、doesntContain メソッドにクロージャを渡すことができます:

$collection = collect([1, 2, 3, 4, 5]);
$collection->doesntContain(function (int $value, int $key) {
   return $value < 5;
});
// false

また、doesntContain メソッドに文字列を渡して、コレクションが指定されたアイテム値を含まないかどうかを判断することもできます:

$collection = collect(['name' => 'Desk', 'price' => 100]);
$collection->doesntContain('Table');
// true
$collection->doesntContain('Desk');
// false

また、doesntContain メソッドにキー/値ペアを渡すこともでき、指定されたペアがコレクションに存在しないかどうかを判断します:

$collection = collect([
   ['product' => 'Desk', 'price' => 200],
   ['product' => 'Chair', 'price' => 100],
]);
$collection->doesntContain('product', 'Bookcase');
// true

doesntContain メソッドは、アイテム値をチェックする際に「緩い」比較を使用します。つまり、整数値を持つ文字列は同じ値の整数と等しいと見なされます。

dot()

dot メソッドは、多次元コレクションを単一レベルのコレクションにフラット化し、「ドット」表記を使用して深さを示します:

$collection = collect(['products' => ['desk' => ['price' => 100]]]);
$flattened = $collection->dot();
$flattened->all();
// ['products.desk.price' => 100]

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' => '', 'position' => 'Developer'],
   ['email' => '', 'position' => 'Designer'],
   ['email' => '', 'position' => 'Developer'],
]);
$employees->duplicates('position');
// [2 => 'Developer']

duplicatesStrict()

このメソッドは、duplicates メソッドと同じシグネチャを持っています。ただし、すべての値は「厳密」比較を使用して比較されます。

each()

each メソッドは、コレクション内のアイテムを反復処理し、各アイテムをクロージャに渡します:

$collection = collect([1, 2, 3, 4]);
$collection->each(function (int $item, int $key) {
   // ...
});

アイテムの反復処理を停止したい場合は、クロージャから false を返すことができます:

$collection->each(function (int $item, int $key) {
   if (/* condition */) {
   return false;
   }
});

eachSpread()

eachSpread メソッドは、コレクションのアイテムを反復処理し、各ネストされたアイテムの値を指定されたコールバックに渡します:

$collection = collect([['John Doe', 35], ['Jane Doe', 33]]);
$collection->eachSpread(function (string $name, int $age) {
   // ...
});

コールバックから false を返すことで、アイテムの反復処理を停止できます:

$collection->eachSpread(function (string $name, int $age) {
   return false;
});

ensure()

ensure メソッドは、コレクションのすべての要素が指定されたタイプまたはタイプのリストであることを確認するために使用できます。そうでない場合、UnexpectedValueException がスローされます:

return $collection->ensure(User::class);
return $collection->ensure([User::class, Customer::class]);

string、int、float、bool、array などのプリミティブタイプも指定できます:

return $collection->ensure('int');

ensure メソッドは、異なるタイプの要素が後でコレクションに追加されないことを保証しません。

every()

every メソッドは、コレクションのすべての要素が指定された真実テストを通過することを確認するために使用できます:

collect([1, 2, 3, 4])->every(function (int $value, int $key) {
   return $value > 2;
});
// false

コレクションが空の場合、every メソッドは true を返します:

$collection = collect([]);
$collection->every(function (int $value, int $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 (int $value, int $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 (int $value, int $key) {
   return $value > 2;
});
// 3

引数なしで first メソッドを呼び出して、コレクション内の最初の要素を取得することもできます。コレクションが空の場合、null が返されます:

collect([1, 2, 3, 4])->first();
// 1

firstOrFail()

firstOrFail メソッドは first メソッドと同一です。ただし、結果が見つからない場合は、Illuminate\Support\ItemNotFoundException 例外がスローされます:

collect([1, 2, 3, 4])->firstOrFail(function (int $value, int $key) {
   return $value > 5;
});
// Throws ItemNotFoundException...

引数なしで firstOrFail メソッドを呼び出して、コレクション内の最初の要素を取得することもできます。コレクションが空の場合、Illuminate\Support\ItemNotFoundException 例外がスローされます:

collect([])->firstOrFail();
// Throws ItemNotFoundException...

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 メソッドに1つの引数を渡すことができます。このシナリオでは、firstWhere メソッドは、指定されたアイテムキーの値が「真」である最初のアイテムを返します:

$collection->firstWhere('age');
// ['name' => 'Linda', 'age' => 14]

flatMap()

flatMap メソッドは、コレクションを反復処理し、各値を指定されたクロージャに渡します。クロージャはアイテムを変更して返すことができ、新しい変更されたアイテムのコレクションを形成します。その後、配列は1レベルフラット化されます:

$collection = collect([
   ['name' => 'Sally'],
   ['school' => 'Arkansas'],
   ['age' => 28]
]);
$flattened = $collection->flatMap(function (array $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'];

必要に応じて、flatten メソッドに「深さ」引数を渡すことができます:

$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']);
// Forget a single key...
$collection->forget('name');
// ['framework' => 'laravel']
// Forget multiple keys...
$collection->forget(['name', 'framework']);
// []

他のほとんどのコレクションメソッドとは異なり、forget は新しい変更されたコレクションを返さず、呼び出されたコレクションを変更します。

forPage()

forPage メソッドは、指定されたページ番号に存在するアイテムを含む新しいコレクションを返します。このメソッドは、ページ番号を最初の引数として、ページごとに表示するアイテムの数を2番目の引数として受け取ります:

$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('age', 34);
// 34

指定されたキーが存在しない場合、コールバックをメソッドのデフォルト値として渡すこともできます。コールバックの結果が返されます:

$collection->get('email', function () {
   return '';
});
//

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->all();
/*
   [
   'account-x10' => [
   ['account_id' => 'account-x10', 'product' => 'Chair'],
   ['account_id' => 'account-x10', 'product' => 'Bookcase'],
   ],
   'account-x11' => [
   ['account_id' => 'account-x11', 'product' => 'Desk'],
   ],
   ]
*/

文字列 key を渡す代わりに、コールバックを渡すことができます。コールバックは、グループ化する値を返す必要があります:

$grouped = $collection->groupBy(function (array $item, int $key) {
   return substr($item['account_id'], -3);
});
$grouped->all();
/*
   [
   '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 (array $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

hasAny()

hasAny メソッドは、指定されたキーのいずれかがコレクションに存在するかどうかを判断します:

$collection = collect(['account_id' => 1, 'product' => 'Desk', 'amount' => 5]);
$collection->hasAny(['product', 'price']);
// true
$collection->hasAny(['name', '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'

値をフォーマットしたい場合は、implode メソッドにクロージャを渡すことができます:

$collection->implode(function (array $item, int $key) {
   return strtoupper($item['product']);
}, ', ');
// DESK, CHAIR

intersect()

intersect メソッドは、指定された array またはコレクションに存在しない元のコレクションから値を削除します。結果のコレクションは、元のコレクションのキーを保持します:

$collection = collect(['Desk', 'Sofa', 'Chair']);
$intersect = $collection->intersect(['Desk', 'Chair', 'Bookcase']);
$intersect->all();
// [0 => 'Desk', 2 => 'Chair']

このメソッドの動作は、Eloquent Collections を使用する際に変更されます。

intersectAssoc()

intersectAssoc メソッドは、元のコレクションを別のコレクションまたは array と比較し、すべての指定されたコレクションに存在するキー/値ペアを返します:

$collection = collect([
   'color' => 'red',
   'size' => 'M',
   'material' => 'cotton'
]);
$intersect = $collection->intersectAssoc([
   'color' => 'blue',
   'size' => 'M',
   'material' => 'polyester'
]);
$intersect->all();
// ['size' => 'M']

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 (array $item, int $key) {
   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 (int $value, int $key) {
   return $value < 3;
});
// 2

引数なしで last メソッドを呼び出すことでも、コレクション内の最後の要素を取得できます。コレクションが空の場合、null が返されます:

collect([1, 2, 3, 4])->last();
// 4

lazy()

lazy メソッドは、アイテムの基になる配列から新しい LazyCollection インスタンスを返します:

$lazyCollection = collect([1, 2, 3, 4])->lazy();
$lazyCollection::class;
// Illuminate\Support\LazyCollection
$lazyCollection->all();
// [1, 2, 3, 4]

これは、非常に多くのアイテムを含む巨大な Collection に対して変換を行う必要がある場合に特に便利です:

$count = $hugeCollection
   ->lazy()
   ->where('country', 'FR')
   ->where('balance', '>', '100')
   ->count();

コレクションを LazyCollection に変換することで、追加のメモリを大量に割り当てる必要がなくなります。元のコレクションはメモリ内にその値を保持し続けますが、後続のフィルターは保持しません。したがって、コレクションの結果をフィルタリングする際に、実質的に追加のメモリは割り当てられません。

macro()

macro 静的メソッドを使用すると、実行時に Collection クラスにメソッドを追加できます。詳細については、コレクションの拡張に関するドキュメントを参照してください。

make()

make 静的メソッドは、新しいコレクションインスタンスを作成します。コレクションの作成セクションを参照してください。

map()

map メソッドはコレクションを反復処理し、各値を指定されたコールバックに渡します。コールバックはアイテムを変更して返すことができ、新しい変更されたアイテムのコレクションを形成します:

$collection = collect([1, 2, 3, 4, 5]);
$multiplied = $collection->map(function (int $item, int $key) {
   return $item * 2;
});
$multiplied->all();
// [2, 4, 6, 8, 10]

他のほとんどのコレクションメソッドと同様に、map は新しいコレクションインスタンスを返します; 呼び出されたコレクションを変更しません。元のコレクションを変換したい場合は、transform メソッドを使用してください。

mapInto()

mapInto() メソッドはコレクションを反復処理し、値をコンストラクタに渡して指定されたクラスの新しいインスタンスを作成します:

class Currency
{
   /**
     * Create a new currency instance.
   */
   function __construct(
   public string $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 (int $even, int $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 (array $item, int $key) {
   return [$item['department'] => $item['name']];
});
$grouped->all();
/*
   [
   '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' => '',
   ],
   [
   'name' => 'Jane',
   'department' => 'Marketing',
   'email' => '',
   ]
]);
$keyed = $collection->mapWithKeys(function (array $item, int $key) {
   return [$item['email'] => $item['name']];
});
$keyed->all();
/*
   [
   '' => 'John',
   '' => '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]
$mode = collect([1, 1, 2, 2])->mode();
// [1, 2]

multiply()

multiply メソッドは、コレクション内のすべてのアイテムの指定された数のコピーを作成します:

$users = collect([
   ['name' => 'User #1', 'email' => ''],
   ['name' => 'User #2', 'email' => ''],
])->multiply(3);
/*
   [
   ['name' => 'User #1', 'email' => ''],
   ['name' => 'User #2', 'email' => ''],
   ['name' => 'User #1', 'email' => ''],
   ['name' => 'User #2', 'email' => ''],
   ['name' => 'User #1', 'email' => ''],
   ['name' => 'User #2', 'email' => ''],
   ]
*/

nth()

nth メソッドは、n 番目の要素からなる新しいコレクションを作成します:

$collection = collect(['a', 'b', 'c', 'd', 'e', 'f']);
$collection->nth(4);
// ['a', 'e']

オプションで、2 番目の引数として開始オフセットを渡すことができます:

$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 の配列分解と組み合わせて、指定された真理テストを通過する要素と通過しない要素を分けることができます:

$collection = collect([1, 2, 3, 4, 5, 6]);
[$underThree, $equalOrAboveThree] = $collection->partition(function (int $i) {
   return $i < 3;
});
$underThree->all();
// [1, 2]
$equalOrAboveThree->all();
// [3, 4, 5, 6]

percentage()

percentage メソッドは、指定された真理テストを通過するコレクション内のアイテムの割合を迅速に決定するために使用できます:

$collection = collect([1, 1, 2, 2, 2, 3]);
$percentage = $collection->percentage(fn ($value) => $value === 1);
// 33.33

デフォルトでは、割合は小数点以下 2 桁に丸められます。ただし、メソッドに 2 番目の引数を提供することで、この動作をカスタマイズできます:

$percentage = $collection->percentage(fn ($value) => $value === 1, precision: 3);
// 33.333

pipe()

pipe メソッドは、コレクションを指定されたクロージャに渡し、実行されたクロージャの結果を返します:

$collection = collect([1, 2, 3]);
$piped = $collection->pipe(function (Collection $collection) {
   return $collection->sum();
});
// 6

pipeInto()

pipeInto メソッドは、指定されたクラスの新しいインスタンスを作成し、コレクションをコンストラクタに渡します:

class ResourceCollection
{
   /**
     * Create a new ResourceCollection instance.
   */
   public function __construct(
   public Collection $collection,
   ) {}
}
$collection = collect([1, 2, 3]);
$resource = $collection->pipeInto(ResourceCollection::class);
$resource->collection->all();
// [1, 2, 3]

pipeThrough()

pipeThrough メソッドは、コレクションを指定されたクロージャの配列に渡し、実行されたクロージャの結果を返します:

use Illuminate\Support\Collection;
$collection = collect([1, 2, 3]);
$result = $collection->pipeThrough([
   function (Collection $collection) {
   return $collection->merge([4, 5]);
   },
   function (Collection $collection) {
   return $collection->sum();
   },
]);
// 15

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']

pluck メソッドは、”ドット” 表記を使用してネストされた値を取得することもサポートしています:

$collection = collect([
   [
   'name' => 'Laracon',
   'speakers' => [
   'first_day' => ['Rosa', 'Judith'],
   ],
   ],
   [
   'name' => 'VueConf',
   'speakers' => [
   'first_day' => ['Abigail', 'Joey'],
   ],
   ],
]);
$plucked = $collection->pluck('speakers.first_day');
$plucked->all();
// [['Rosa', 'Judith'], ['Abigail', 'Joey']]

重複するキーが存在する場合、最後の一致する要素がプルックされたコレクションに挿入されます:

$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]

pop メソッドに整数を渡すことで、コレクションの末尾から複数のアイテムを削除して返すことができます:

$collection = collect([1, 2, 3, 4, 5]);
$collection->pop(3);
// collect([5, 4, 3])
$collection->all();
// [1, 2]

prepend()

prepend メソッドは、コレクションの先頭にアイテムを追加します:

$collection = collect([1, 2, 3, 4, 5]);
$collection->prepend(0);
$collection->all();
// [0, 1, 2, 3, 4, 5]

追加されたアイテムのキーを指定するために、2 番目の引数を渡すこともできます:

$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)

コレクションインスタンスに要求されたアイテムよりも少ないアイテムがある場合、random メソッドは InvalidArgumentException をスローします。

random メソッドは、現在のコレクションインスタンスを受け取るクロージャも受け入れます:

use Illuminate\Support\Collection;
$random = $collection->random(fn (Collection $items) => min(10, count($items)));
$random->all();
// [1, 2, 3, 4, 5] - (retrieved randomly)

range()

range メソッドは、指定された範囲内の整数を含むコレクションを返します:

$collection = collect()->range(3, 6);
$collection->all();
// [3, 4, 5, 6]

reduce()

reduce メソッドは、コレクションを単一の値に減らし、各反復の結果を次の反復に渡します:

$collection = collect([1, 2, 3]);
$total = $collection->reduce(function (?int $carry, int $item) {
   return $carry + $item;
});
// 6

最初の反復の $carry の値は null ですが、reduce に 2 番目の引数を渡すことで初期値を指定できます:

$collection->reduce(function (int $carry, int $item) {
   return $carry + $item;
}, 4);
// 10

reduce メソッドは、連想コレクション内の配列キーも指定されたコールバックに渡します:

$collection = collect([
   'usd' => 1400,
   'gbp' => 1200,
   'eur' => 1000,
]);
$ratio = [
   'usd' => 1,
   'gbp' => 1.37,
   'eur' => 1.22,
];
$collection->reduce(function (int $carry, int $value, int $key) use ($ratio) {
   return $carry + ($value * $ratio[$key]);
});
// 4264

reduceSpread()

reduceSpread メソッドは、コレクションを値の配列に減らし、各反復の結果を次の反復に渡します。このメソッドは reduce メソッドに似ていますが、複数の初期値を受け入れることができます:

[$creditsRemaining, $batch] = Image::where('status', 'unprocessed')
   ->get()
   ->reduceSpread(function (int $creditsRemaining, Collection $batch, Image $image) {
   if ($creditsRemaining >= $image->creditsRequired()) {
   $batch->push($image);
   $creditsRemaining -= $image->creditsRequired();
   }
   return [$creditsRemaining, $batch];
   }, $creditsAvailable, collect());

reject()

reject メソッドは、指定されたクロージャを使用してコレクションをフィルタリングします。クロージャは、アイテムが結果のコレクションから削除されるべき場合 true を返す必要があります:

$collection = collect([1, 2, 3, 4]);
$filtered = $collection->reject(function (int $value, int $key) {
   return $value > 2;
});
$filtered->all();
// [1, 2]

reject メソッドの逆については、filter メソッドを参照してください。

replace()

replace メソッドは merge に似た動作をしますが、文字列キーを持つ一致するアイテムを上書きするだけでなく、replace メソッドは一致する数値キーを持つアイテムも上書きします:

$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 をメソッドの 2 番目の引数として渡します:

collect([2, 4, 6, 8])->search('4', strict: true);
// false

または、指定された真実テストを通過する最初のアイテムを検索するために独自のクロージャを提供できます:

collect([2, 4, 6, 8])->search(function (int $item, int $key) {
   return $item > 5;
});
// 2

select()

select メソッドは、コレクションから指定されたキーを選択します。これは、SQL SELECT ステートメントに似ています:

$users = collect([
   ['name' => 'Taylor Otwell', 'role' => 'Developer', 'status' => 'active'],
   ['name' => 'Victoria Faith', 'role' => 'Researcher', 'status' => 'active'],
]);
$users->select(['name', 'role']);
/*
   [
   ['name' => 'Taylor Otwell', 'role' => 'Developer'],
   ['name' => 'Victoria Faith', 'role' => 'Researcher'],
   ],
*/

shift()

shift メソッドは、コレクションから最初のアイテムを削除して返します:

$collection = collect([1, 2, 3, 4, 5]);
$collection->shift();
// 1
$collection->all();
// [2, 3, 4, 5]

shift メソッドに整数を渡すことで、コレクションの先頭から複数のアイテムを削除して返すことができます:

$collection = collect([1, 2, 3, 4, 5]);
$collection->shift(3);
// collect([1, 2, 3])
$collection->all();
// [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]

skipUntil()

skipUntil メソッドは、指定されたコールバックが true を返すまでコレクションのアイテムをスキップし、その後、コレクション内の残りのアイテムを新しいコレクションインスタンスとして返します:

$collection = collect([1, 2, 3, 4]);
$subset = $collection->skipUntil(function (int $item) {
   return $item >= 3;
});
$subset->all();
// [3, 4]

指定された値が見つかるまで、skipUntil メソッドに単純な値を渡してすべてのアイテムをスキップすることもできます:

$collection = collect([1, 2, 3, 4]);
$subset = $collection->skipUntil(3);
$subset->all();
// [3, 4]

指定された値が見つからない場合や、コールバックが true を返さない場合、skipUntil メソッドは空のコレクションを返します。

skipWhile()

skipWhile メソッドは、指定されたコールバックが true を返す間、コレクションのアイテムをスキップし、その後、コレクション内の残りのアイテムを新しいコレクションとして返します:

$collection = collect([1, 2, 3, 4]);
$subset = $collection->skipWhile(function (int $item) {
   return $item <= 3;
});
$subset->all();
// [4]

コールバックが false を返さない場合、skipWhile メソッドは空のコレクションを返します。

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]

返されるスライスのサイズを制限したい場合は、メソッドの 2 番目の引数として希望のサイズを渡します:

$slice = $collection->slice(4, 2);
$slice->all();
// [5, 6]

返されるスライスはデフォルトでキーを保持します。元のキーを保持したくない場合は、values メソッドを使用して再インデックス化できます。

sliding()

sliding メソッドは、コレクション内のアイテムの “スライディングウィンドウ” ビューを表す新しいコレクションのチャンクを返します:

$collection = collect([1, 2, 3, 4, 5]);
$chunks = $collection->sliding(2);
$chunks->toArray();
// [[1, 2], [2, 3], [3, 4], [4, 5]]

これは、eachSpread メソッドと組み合わせて特に便利です:

$transactions->sliding(2)->eachSpread(function (Collection $previous, Collection $current) {
   $current->total = $previous->total + $current->amount;
});

オプションで、各チャンクの最初のアイテム間の距離を決定する 2 番目の “ステップ” 値を渡すことができます:

$collection = collect([1, 2, 3, 4, 5]);
$chunks = $collection->sliding(3, step: 2);
$chunks->toArray();
// [[1, 2, 3], [3, 4, 5]]

sole()

sole メソッドは、指定された真理テストを通過するコレクション内の最初の要素を返しますが、真理テストが正確に 1 つの要素に一致する場合のみ返します:

collect([1, 2, 3, 4])->sole(function (int $value, int $key) {
   return $value === 2;
});
// 2

sole メソッドにキー/値ペアを渡すこともでき、指定されたペアに一致するコレクション内の最初の要素を返しますが、正確に 1 つの要素が一致する場合のみ返します:

$collection = collect([
   ['product' => 'Desk', 'price' => 200],
   ['product' => 'Chair', 'price' => 100],
]);
$collection->sole('product', 'Chair');
// ['product' => 'Chair', 'price' => 100]

また、sole メソッドを引数なしで呼び出して、コレクションに要素が 1 つだけある場合に最初の要素を取得することもできます:

$collection = collect([
   ['product' => 'Desk', 'price' => 200],
]);
$collection->sole();
// ['product' => 'Desk', 'price' => 200]

sole メソッドによって返されるべき要素がコレクションに存在しない場合、\Illuminate\Collections\ItemNotFoundException 例外がスローされます。返されるべき要素が 1 つ以上ある場合、\Illuminate\Collections\MultipleItemsFoundException がスローされます。

some()

contains メソッドのエイリアスです。

sort()

sort メソッドはコレクションをソートします。ソートされたコレクションは元の配列キーを保持するため、次の例では values メソッドを使用してキーを連続番号のインデックスにリセットします:

$collection = collect([5, 3, 1, 2, 4]);
$sorted = $collection->sort();
$sorted->values()->all();
// [1, 2, 3, 4, 5]

ソートのニーズがより高度な場合は、sort にコールバックを渡して独自のアルゴリズムを使用できます。コレクションの sort メソッドが内部で利用する uasort に関する PHP ドキュメントを参照してください。

ネストされた配列やオブジェクトのコレクションをソートする必要がある場合は、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],
   ]
*/

sortBy メソッドは、2 番目の引数としてソートフラグを受け入れます:

$collection = collect([
   ['title' => 'Item 1'],
   ['title' => 'Item 12'],
   ['title' => 'Item 3'],
]);
$sorted = $collection->sortBy('title', SORT_NATURAL);
$sorted->values()->all();
/*
   [
   ['title' => 'Item 1'],
   ['title' => 'Item 3'],
   ['title' => 'Item 12'],
   ]
*/

また、コレクションの値をソートする方法を決定するために独自のクロージャを渡すこともできます:

$collection = collect([
   ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
   ['name' => 'Chair', 'colors' => ['Black']],
   ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
]);
$sorted = $collection->sortBy(function (array $product, int $key) {
   return count($product['colors']);
});
$sorted->values()->all();
/*
   [
   ['name' => 'Chair', 'colors' => ['Black']],
   ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
   ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
   ]
*/

複数の属性でコレクションをソートしたい場合は、sortBy メソッドにソート操作の配列を渡すことができます。各ソート操作は、ソートしたい属性と希望するソートの方向を含む配列である必要があります:

$collection = collect([
   ['name' => 'Taylor Otwell', 'age' => 34],
   ['name' => 'Abigail Otwell', 'age' => 30],
   ['name' => 'Taylor Otwell', 'age' => 36],
   ['name' => 'Abigail Otwell', 'age' => 32],
]);
$sorted = $collection->sortBy([
   ['name', 'asc'],
   ['age', 'desc'],
]);
$sorted->values()->all();
/*
   [
   ['name' => 'Abigail Otwell', 'age' => 32],
   ['name' => 'Abigail Otwell', 'age' => 30],
   ['name' => 'Taylor Otwell', 'age' => 36],
   ['name' => 'Taylor Otwell', 'age' => 34],
   ]
*/

複数の属性でコレクションをソートする場合、各ソート操作を定義するクロージャを提供することもできます:

$collection = collect([
   ['name' => 'Taylor Otwell', 'age' => 34],
   ['name' => 'Abigail Otwell', 'age' => 30],
   ['name' => 'Taylor Otwell', 'age' => 36],
   ['name' => 'Abigail Otwell', 'age' => 32],
]);
$sorted = $collection->sortBy([
   fn (array $a, array $b) => $a['name'] <=> $b['name'],
   fn (array $a, array $b) => $b['age'] <=> $a['age'],
]);
$sorted->values()->all();
/*
   [
   ['name' => 'Abigail Otwell', 'age' => 32],
   ['name' => 'Abigail Otwell', 'age' => 30],
   ['name' => 'Taylor Otwell', 'age' => 36],
   ['name' => 'Taylor Otwell', 'age' => 34],
   ]
*/

sortByDesc()

このメソッドは、sortBy メソッドと同じシグネチャを持ちますが、コレクションを逆の順序でソートします。

sortDesc()

このメソッドは、sort メソッドと同じように、コレクションを逆の順序でソートします:

$collection = collect([5, 3, 1, 2, 4]);
$sorted = $collection->sortDesc();
$sorted->values()->all();
// [5, 4, 3, 2, 1]

sort とは異なり、sortDesc にコールバックを渡すことはできません。代わりに、sort メソッドを使用して比較を反転させる必要があります。

sortKeys()

sortKeys メソッドは、基になる連想配列のキーでコレクションをソートします:

$collection = collect([
   'id' => 22345,
   'first' => 'John',
   'last' => 'Doe',
]);
$sorted = $collection->sortKeys();
$sorted->all();
/*
   [
   'first' => 'John',
   'id' => 22345,
   'last' => 'Doe',
   ]
*/

sortKeysDesc()

このメソッドは、sortKeys メソッドと同じシグネチャを持ちますが、コレクションを逆の順序でソートします。

sortKeysUsing()

sortKeysUsing メソッドは、コールバックを使用して基になる連想配列のキーでコレクションをソートします:

$collection = collect([
   'ID' => 22345,
   'first' => 'John',
   'last' => 'Doe',
]);
$sorted = $collection->sortKeysUsing('strnatcasecmp');
$sorted->all();
/*
   [
   'first' => 'John',
   'ID' => 22345,
   'last' => 'Doe',
   ]
*/

コールバックは、0 より小さい、等しい、または大きい整数を返す比較関数でなければなりません。詳細については、sortKeysUsing メソッドが内部で利用する PHP 関数に関する PHP ドキュメントを参照してください。uksort

splice()

splice メソッドは、指定されたインデックスからアイテムのスライスを削除して返します:

$collection = collect([1, 2, 3, 4, 5]);
$chunk = $collection->splice(2);
$chunk->all();
// [3, 4, 5]
$collection->all();
// [1, 2]

結果のコレクションのサイズを制限するために、2 番目の引数を渡すことができます:

$collection = collect([1, 2, 3, 4, 5]);
$chunk = $collection->splice(2, 1);
$chunk->all();
// [3]
$collection->all();
// [1, 2, 4, 5]

さらに、削除されたアイテムを置き換える新しいアイテムを含む 3 番目の引数を渡すこともできます:

$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->all();
// [[1, 2], [3, 4], [5]]

splitIn()

splitIn メソッドは、コレクションを指定された数のグループに分割し、非端末グループを完全に埋めてから、残りを最終グループに割り当てます:

$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
$groups = $collection->splitIn(3);
$groups->all();
// [[1, 2, 3, 4], [5, 6, 7, 8], [9, 10]]

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 (array $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]

takeUntil()

takeUntil メソッドは、指定されたコールバックが true を返すまでコレクション内のアイテムを返します:

$collection = collect([1, 2, 3, 4]);
$subset = $collection->takeUntil(function (int $item) {
   return $item >= 3;
});
$subset->all();
// [1, 2]

指定された値が見つかるまで、takeUntil メソッドに単純な値を渡してアイテムを取得することもできます:

$collection = collect([1, 2, 3, 4]);
$subset = $collection->takeUntil(3);
$subset->all();
// [1, 2]

指定された値が見つからない場合や、コールバックが true を返さない場合、takeUntil メソッドはコレクション内のすべてのアイテムを返します。

takeWhile()

takeWhile メソッドは、指定されたコールバックが false を返すまでコレクション内のアイテムを返します:

$collection = collect([1, 2, 3, 4]);
$subset = $collection->takeWhile(function (int $item) {
   return $item < 3;
});
$subset->all();
// [1, 2]

コールバックが false を返さない場合、takeWhile メソッドはコレクション内のすべてのアイテムを返します。

tap()

tap メソッドは、コレクションを指定されたコールバックに渡し、コレクション自体に影響を与えずに特定のポイントでコレクションに “タップ” してアイテムで何かを行うことを可能にします。コレクションは tap メソッドによって返されます:

collect([2, 4, 3, 1, 5])
   ->sort()
   ->tap(function (Collection $collection) {
   Log::debug('Values after sorting', $collection->values()->all());
   })
   ->shift();
// 1

times()

times 静的メソッドは、指定された回数だけ与えられたクロージャを呼び出して新しいコレクションを作成します:

$collection = Collection::times(10, function (int $number) {
   return $number * 9;
});
$collection->all();
// [9, 18, 27, 36, 45, 54, 63, 72, 81, 90]

toArray()

toArray メソッドは、コレクションをプレーンな PHP array に変換します。コレクションの値が Eloquent モデルである場合、モデルも配列に変換されます:

$collection = collect(['name' => 'Desk', 'price' => 200]);
$collection->toArray();
/*
   [
   ['name' => 'Desk', 'price' => 200],
   ]
*/

toArray は、Arrayable のインスタンスであるコレクションのすべてのネストされたオブジェクトを配列に変換します。コレクションの基になる生の配列を取得したい場合は、代わりに 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 (int $item, int $key) {
   return $item * 2;
});
$collection->all();
// [2, 4, 6, 8, 10]

他のほとんどのコレクションメソッドとは異なり、transform はコレクション自体を変更します。新しいコレクションを作成したい場合は、map メソッドを使用してください。

undot()

undot メソッドは、”ドット” 表記を使用する単一次元コレクションを多次元コレクションに展開します:

$person = collect([
   'name.first_name' => 'Marie',
   'name.last_name' => 'Valentine',
   'address.line_1' => '2992 Eagle Drive',
   'address.line_2' => '',
   'address.suburb' => 'Detroit',
   'address.state' => 'MI',
   'address.postcode' => '48219'
]);
$person = $person->undot();
$person->toArray();
/*
   [
   "name" => [
   "first_name" => "Marie",
   "last_name" => "Valentine",
   ],
   "address" => [
   "line_1" => "2992 Eagle Drive",
   "line_2" => "",
   "suburb" => "Detroit",
   "state" => "MI",
   "postcode" => "48219",
   ],
   ]
*/

union()

union メソッドは、指定された配列をコレクションに追加します。指定された配列に元のコレクションに既に存在するキーが含まれている場合、元のコレクションの値が優先されます:

$collection = collect([1 => ['a'], 2 => ['b']]);
$union = $collection->union([3 => ['c'], 1 => ['d']]);
$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 メソッドに独自のクロージャを渡して、アイテムのユニーク性を決定する値を指定することもできます:

$unique = $collection->unique(function (array $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 $collection) {
   return $collection->push(4);
});
$collection->unless(false, function (Collection $collection) {
   return $collection->push(5);
});
$collection->all();
// [1, 2, 3, 5]

unless メソッドに 2 番目のコールバックを渡すことができます。最初の引数が true に評価されると、2 番目のコールバックが実行されます:

$collection = collect([1, 2, 3]);
$collection->unless(true, function (Collection $collection) {
   return $collection->push(4);
}, function (Collection $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'

value()

value メソッドは、コレクションの最初の要素から指定された値を取得します:

$collection = collect([
   ['product' => 'Desk', 'price' => 200],
   ['product' => 'Speaker', 'price' => 400],
]);
$value = $collection->value('price');
// 200

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 に評価されると、指定されたコールバックを実行します。コレクションインスタンスと when メソッドに渡された最初の引数がクロージャに提供されます:

$collection = collect([1, 2, 3]);
$collection->when(true, function (Collection $collection, int $value) {
   return $collection->push(4);
});
$collection->when(false, function (Collection $collection, int $value) {
   return $collection->push(5);
});
$collection->all();
// [1, 2, 3, 4]

when メソッドに 2 番目のコールバックを渡すことができます。最初の引数が false に評価されると、2 番目のコールバックが実行されます:

$collection = collect([1, 2, 3]);
$collection->when(false, function (Collection $collection, int $value) {
   return $collection->push(4);
}, function (Collection $collection) {
   return $collection->push(5);
});
$collection->all();
// [1, 2, 3, 5]

when の逆については、unless メソッドを参照してください。

whenEmpty()

whenEmpty メソッドは、コレクションが空のときに指定されたコールバックを実行します:

$collection = collect(['Michael', 'Tom']);
$collection->whenEmpty(function (Collection $collection) {
   return $collection->push('Adam');
});
$collection->all();
// ['Michael', 'Tom']
$collection = collect();
$collection->whenEmpty(function (Collection $collection) {
   return $collection->push('Adam');
});
$collection->all();
// ['Adam']

コレクションが空でないときに実行される 2 番目のクロージャを whenEmpty メソッドに渡すことができます:

$collection = collect(['Michael', 'Tom']);
$collection->whenEmpty(function (Collection $collection) {
   return $collection->push('Adam');
}, function (Collection $collection) {
   return $collection->push('Taylor');
});
$collection->all();
// ['Michael', 'Tom', 'Taylor']

whenEmpty の逆については、whenNotEmpty メソッドを参照してください。

whenNotEmpty()

whenNotEmpty メソッドは、コレクションが空でないときに指定されたコールバックを実行します:

$collection = collect(['michael', 'tom']);
$collection->whenNotEmpty(function (Collection $collection) {
   return $collection->push('adam');
});
$collection->all();
// ['michael', 'tom', 'adam']
$collection = collect();
$collection->whenNotEmpty(function (Collection $collection) {
   return $collection->push('adam');
});
$collection->all();
// []

コレクションが空のときに実行される 2 番目のクロージャを whenNotEmpty メソッドに渡すことができます:

$collection = collect();
$collection->whenNotEmpty(function (Collection $collection) {
   return $collection->push('adam');
}, function (Collection $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 メソッドを使用してください。

オプションで、2番目のパラメータとして比較演算子を渡すことができます。サポートされている演算子は: ‘===’, ‘!==’, ‘!=’, ‘==’, ‘=’, ‘<>’, ‘>’, ‘<’, ‘>=’, および ‘<=’:

$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\Models\User;
use App\Models\Post;
$collection = collect([
   new User,
   new User,
   new Post,
]);
$filtered = $collection->whereInstanceOf(User::class);
$filtered->all();
// [App\Models\User, App\Models\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 メソッドは、適用可能な場合に指定された値をコレクションにラップします:

use Illuminate\Support\Collection;
$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]]

Higher Order Messages

コレクションは「高次メッセージ」をサポートしており、コレクションに対して一般的なアクションを実行するためのショートカットです。高次メッセージを提供するコレクションメソッドは: average, avg, contains, each, every, filter, first, flatMap, groupBy, keyBy, map, max, min, partition, reject, skipUntil, skipWhile, some, sortBy, sortByDesc, sum, takeUntil, takeWhile, および unique.

各高次メッセージは、コレクションインスタンスの動的プロパティとしてアクセスできます。たとえば、each 高次メッセージを使用して、コレクション内の各オブジェクトにメソッドを呼び出すことができます:

use App\Models\User;
$users = User::where('votes', '>', 500)->get();
$users->each->markAsVip();

同様に、sum 高次メッセージを使用して、ユーザーのコレクションの「投票」の合計数を集計できます:

$users = User::where('group', 'Development')->get();
return $users->sum->votes;

Lazy Collections

Introduction

Laravel のレイジーコレクションについてさらに学ぶ前に、PHP ジェネレーターに慣れるための時間を取ってください。

すでに強力な Collection クラスを補完するために、LazyCollection クラスは PHP のジェネレーターを活用して、メモリ使用量を低く抑えながら非常に大きなデータセットで作業できるようにします。

たとえば、アプリケーションが Laravel のコレクションメソッドを利用してログを解析しながら、マルチギガバイトのログファイルを処理する必要があると想像してください。一度にファイル全体をメモリに読み込むのではなく、レイジーコレクションを使用して、特定の時点でファイルの小さな部分だけをメモリに保持することができます:

use App\Models\LogEntry;
use Illuminate\Support\LazyCollection;
LazyCollection::make(function () {
   $handle = fopen('log.txt', 'r');
   while (($line = fgets($handle)) !== false) {
   yield $line;
   }
})->chunk(4)->map(function (array $lines) {
   return LogEntry::fromLines($lines);
})->each(function (LogEntry $logEntry) {
   // Process the log entry...
});

または、10,000 の Eloquent モデルを反復処理する必要があると想像してください。従来の Laravel コレクションを使用すると、すべての 10,000 の Eloquent モデルを同時にメモリに読み込む必要があります:

use App\Models\User;
$users = User::all()->filter(function (User $user) {
   return $user->id > 500;
});

ただし、クエリビルダーの cursor メソッドは LazyCollection インスタンスを返します。これにより、データベースに対して単一のクエリを実行しながら、同時にメモリに読み込まれる Eloquent モデルを 1 つだけ保持することができます。この例では、filter コールバックは、実際に各ユーザーを個別に反復処理するまで実行されず、メモリ使用量が大幅に削減されます:

use App\Models\User;
$users = User::cursor()->filter(function (User $user) {
   return $user->id > 500;
});
foreach ($users as $user) {
   echo $user->id;
}

Creating Lazy Collections

レイジーコレクションインスタンスを作成するには、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 chunkWhile collapse collect combine concat contains containsStrict count countBy crossJoin dd diff diffAssoc diffKeys dump duplicates duplicatesStrict each eachSpread every except filter first firstOrFail firstWhere flatMap flatten flip forPage get groupBy has implode intersect intersectAssoc 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 sole 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

コレクションを変更するメソッド（shift, pop, prepend など）は、LazyCollection クラスでは 利用できません。

Lazy Collection Methods

Enumerable コントラクトで定義されたメソッドに加えて、LazyCollection クラスには次のメソッドが含まれています:

takeUntilTimeout()

takeUntilTimeout メソッドは、指定された時間まで値を列挙する新しいレイジーコレクションを返します。その時間が過ぎると、コレクションは列挙を停止します:

$lazyCollection = LazyCollection::times(INF)
   ->takeUntilTimeout(now()->addMinute());
$lazyCollection->each(function (int $number) {
   dump($number);
   sleep(1);
});
// 1
// 2
// ...
// 58
// 59

このメソッドの使用例を示すために、カーソルを使用してデータベースから請求書を送信するアプリケーションを想像してください。15 分ごとに実行され、最大 14 分間のみ請求書を処理するスケジュールされたタスクを定義できます:

use App\Models\Invoice;
use Illuminate\Support\Carbon;
Invoice::pending()->cursor()
   ->takeUntilTimeout(
   Carbon::createFromTimestamp(LARAVEL_START)->add(14, 'minutes')
   )
   ->each(fn (Invoice $invoice) => $invoice->submit());

tapEach()

each メソッドは、コレクション内の各アイテムに対してすぐに指定されたコールバックを呼び出しますが、tapEach メソッドは、アイテムがリストから 1 つずつ取り出されるときにのみ指定されたコールバックを呼び出します:

// Nothing has been dumped so far...
$lazyCollection = LazyCollection::times(INF)->tapEach(function (int $value) {
   dump($value);
});
// Three items are dumped...
$array = $lazyCollection->take(3)->all();
// 1
// 2
// 3

throttle()

throttle メソッドは、レイジーコレクションをスロットルし、指定された秒数後に各値を返します。このメソッドは、外部 API とやり取りする場合に特に便利です。これにより、受信リクエストのレート制限が行われます:

use App\Models\User;
User::where('vip', true)
   ->cursor()
   ->throttle(seconds: 1)
   ->each(function (User $user) {
   // Call external API...
   });

remember()

remember メソッドは、すでに列挙された値を記憶し、次回のコレクション列挙時に再取得しない新しいレイジーコレクションを返します:

// No query has been executed yet...
$users = User::cursor()->remember();
// The query is executed...
// The first 5 users are hydrated from the database...
$users->take(5)->all();
// First 5 users come from the collection's cache...
// The rest are hydrated from the database...
$users->take(20)->all();