︙

Collections

Table of Contents

Introduction
- Creating Collections
- Extending Collections
Available Methods
Higher Order Messages
Lazy Collections

Introduction

Illuminate\Support\Collection class は、data の配列を操作するための流暢で便利なラッパーを提供します。例えば、次のコードをご覧ください。collecthelper を使用して新しい collection インスタンスを array から作成し、各要素でstrtoupper関数を実行し、その後、すべての空の要素を削除します:

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

ご覧の通り、Collection class はそのメソッドを連鎖させて、基本的な array のフルエントなマッピングとリデューシングを実行することを可能にします。一般的に、 collections は不変であり、すべてのCollection method は全く新しいCollectionインスタンスを返すという意味です。

Collections を作成する

上記で述べたように、collectヘルパーは与えられた array に対して新たなIlluminate\Support\Collectionインスタンスを返します。したがって、 collection の作成は次のように簡単にできます：

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

NOTE

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

Collections は"macroable"で、これにより実行時にCollectionclass に追加のメソッドを追加することができます。 Illuminate\Support\Collectionクラスのmacromethod は、あなたのマクロが呼ばれたときに実行されるクロージャを受け入れます。マクロのクロージャは、$thisを介して Collections の他のメソッドにアクセスでき、まるで本当の method であるかのように動きます。例えば、以下のコードは、toUppermethod をCollectionclass に追加します：

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の method でservice providerの中に collection マクロを宣言するべきです。

Macro 引数

必要であれば、追加の引数を受け入れるマクロを定義することができます：

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');

Available Methods

残りの大部分の collection ドキュメンテーションでは、Collection class で利用可能な各 method について話し合います。覚えておいてください、これらのメソッドはすべて、基礎となる array を流暢に操作するために連鎖させることができます。さらに、ほぼすべての method は新しいCollectionインスタンスを返します。これにより、必要に応じて collection の元のコピーを保存することができます。

all average avg 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 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

Method Listing

`all()`

all method は、 collection によって表される基礎となる array を返します:

collect([1, 2, 3])->all();

// [1, 2, 3]

`average()`

avg method の別名。

`avg()`

avg method は指定された key の平均 value を返します：

$average = collect([
    ['foo' => 10],
    ['foo' => 10],
    ['foo' => 20],
    ['foo' => 40]
])->avg('foo');

// 20

$average = collect([1, 1, 2, 4])->avg();

// 2

`chunk()`

chunk method は、指定されたサイズの複数の小さな collection に collections を分割します：

$collection = collect([1, 2, 3, 4, 5, 6, 7]);

$chunks = $collection->chunk(4);

$chunks->all();

// [[1, 2, 3, 4], [5, 6, 7]]

この method は、Bootstrap のようなグリッドシステムを使って作業する際に、viewsで特に便利です。例えば、グリッドに表示したいEloquentの models の collection があると想像してみてください。

@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 method は、与えられたコールバックの評価に基づいて collection を複数の小さな collections に分割します。クロージャーに渡される$chunkvariable は、前の要素を検査するために使用できます：

$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 method は、 collection としての arrays の集まりを single でフラットな collection にまとめます。

$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 method は、現在の collection にあるアイテムを使用して新しいCollectionインスタンスを返します。

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

$collectionB = $collectionA->collect();

$collectionB->all();

// [1, 2, 3]

collect method は主にlazy collectionsを標準的なCollectionインスタンスに変換するのに役立ちます：

$lazyCollection = LazyCollection::make(function () {
    yield 1;
    yield 2;
    yield 3;
});

$collection = $lazyCollection->collect();

$collection::class;

// 'Illuminate\Support\Collection'

$collection->all();

// [1, 2, 3]

NOTE

collect method は、Enumerableのインスタンスがあり、非遅延の collection インスタンスが必要な場合に特に便利です。 collect()はEnumerableの契約の一部であるため、安全に使用してCollectionインスタンスを取得できます。

`combine()`

combine method は、 collection の values を keys として、別の array または collection の values と組み合わせます:

$collection = collect(['name', 'age']);

$combined = $collection->combine(['George', 29]);

$combined->all();

// ['name' => 'George', 'age' => 29]

`concat()`

concat method appends 指定された array やコレクションの values を別の collection の末尾に追加します：

$collection = collect(['John Doe']);

$concatenated = $collection->concat(['Jane Doe'])->concat(['name' => 'Johnny Doe']);

$concatenated->all();

// ['John Doe', 'Jane Doe', 'Johnny Doe']

concat method は、元の collection に連結されたアイテムの keys を数値で再インデックスします。連想的な collections における keys を維持するには、merge method を参照してください。

`contains()`

contains method は、指定したアイテムが collection に含まれているかどうかを判断します。与えられた真偽 test に一致する collection 内の要素が存在するかどうかを判断するために、クロージャをcontains method に渡すことができます。

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

$collection->contains(function (int $value, int $key) {
    return $value > 5;
});

// false

あるいは、contains method に string を渡すことで、その collection が特定のアイテムの value を含んでいるかどうかを判断することもできます：

$collection = collect(['name' => 'Desk', 'price' => 100]);

$collection->contains('Desk');

// true

$collection->contains('New York');

// false

また、キー / value ペアをcontains method に渡すこともできます。これは、指定されたペアが collection 内に存在するかどうかを判断します。

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

$collection->contains('product', 'Bookcase');

// false

containsの method は項目の values をチェックする際に"ルーズ"な比較を使用します。つまり、整数値を持つ string は同じ values を持つ整数と同等と見なされます。"厳密な"比較でフィルタリングを行うためには、containsStrictの method を使用してください。

containsの逆のためには、doesntContain method を参照してください。

`containsOneItem()`

containsOneItem method は、 collection が single のアイテムを含んでいるかどうかを判断します。

collect([])->containsOneItem();

// false

collect(['1'])->containsOneItem();

// true

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

// false

`containsStrict()`

この method は、containsメソッドと同じ signature を持っていますが、すべての values は strict な比較で比較されます。

NOTE

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

`count()`

count method は、 collection 内のアイテムの総数を返します:

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

$collection->count();

// 4

`countBy()`

countBymethod は collection 内の values の出現回数を数えます。 default では、method はすべての要素の出現回数を数え、collection 内の特定の types の要素の数を数えることができます：

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

$counted = $collection->countBy();

$counted->all();

// [1 => 1, 2 => 3, 3 => 1]

全てのアイテムを custom value で数えるために、countBy method にクロージャを渡します：

$collection = collect(['alice@gmail.com', 'bob@yahoo.com', 'carlos@gmail.com']);

$counted = $collection->countBy(function (string $email) {
    return substr(strrchr($email, "@"), 1);
});

$counted->all();

// ['gmail.com' => 2, 'yahoo.com' => 1]

`crossJoin()`

crossJoin method は、与えられた arrays や collections の中でコレクションの values をクロスジョインし、可能なすべての順列を持つデカルト積を返します：

$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 method は、collection のアイテムをダンプし、scripts の実行を終了します：

$collection = collect(['John Doe', 'Jane Doe']);

$collection->dd();

/*
    Collection {
        #items: array:2 [
            0 => "John Doe"
            1 => "Jane Doe"
        ]
    }
*/

スクリプトの実行を停止したくない場合は、代わりにdump method を使用してください。

`diff()`

diff method は、その values に基づいて、 collection を別の collection またはプレーンな PHP array と比較します。この method は、与えられた collection に存在しない元の collection の values を返します。

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

$diff = $collection->diff([2, 4, 6, 8]);

$diff->all();

// [1, 3, 5]

NOTE

このメソッドの振る舞いは、Eloquent Collectionsを使用すると変更されます。

`diffAssoc()`

diffAssocの method は、collection を別の collection または普通の PHP arrayと、keys と values に基づいて比較します。この method は、元の collection の keys/values のペアを返しますが、それらは指定された collection には存在しません:

$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はインデックスの比較のための user が提供するコールバック関数を受け入れます：

$collection = collect([
    'color' => 'orange',
    'type' => 'fruit',
    'remain' => 6,
]);

$diff = $collection->diffAssocUsing([
    'Color' => 'yellow',
    'Type' => 'fruit',
    'Remain' => 3,
], 'strnatcasecmp');

$diff->all();

// ['color' => 'orange', 'remain' => 6]

コールバックは、ゼロより小さい、等しい、またはゼロより大きい integer を返す比較関数でなければなりません。より詳しい説明は、内部でdiffAssocUsing method が利用している PHP 関数である array_diff_uassoc についての PHP ドキュメンテーションを参照してください。

`diffKeys()`

diffKeys method は、その keys に基づいて、他の collection またはプレーンな PHP のarrayと collection を比較します。この method は、指定された collection に存在しない元の collection のキー/ value のペアを返します：

$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 method は、 collection が指定した項目を含んでいないかどうかを判断します。 doesntContain method にクロージャを渡して、 collection 内に指定した真偽 test に一致する要素が存在しないかどうかを判断することもできます。

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

$collection->doesntContain(function (int $value, int $key) {
    return $value < 5;
});

// false

あるいは、与えられたアイテムの value が collection に含まれていないかどうかを判断するために、doesntContain method に string を渡すこともできます。

$collection = collect(['name' => 'Desk', 'price' => 100]);

$collection->doesntContain('Table');

// true

$collection->doesntContain('Desk');

// false

また、キー/ value ペアを doesntContain method に渡すこともでき、そのペアが collection に存在しないかどうかを判断します。

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

$collection->doesntContain('product', 'Bookcase');

// true

doesntContainの method は、アイテムの values を確認する際にルーズな比較を使用します。つまり、整数 values を持つ string は、同じ values を持つ整数と等しいとみなされます。

`dot()`

dot method は多次元の collection を"dot"表記を使用して深さを示す single レベルの collection に平坦化します：

$collection = collect(['products' => ['desk' => ['price' => 100]]]);

$flattened = $collection->dot();

$flattened->all();

// ['products.desk.price' => 100]

`dump()`

dump method は、コレクションのアイテムをダンプします：

$collection = collect(['John Doe', 'Jane Doe']);

$collection->dump();

/*
    Collection {
        #items: array:2 [
            0 => "John Doe"
            1 => "Jane Doe"
        ]
    }
*/

collection のダンプ後にスクリプトの実行を停止したい場合は、代わりに dd method を使用してください。

`duplicates()`

duplicates method は、 collection から重複した values を取得して返します。

$collection = collect(['a', 'b', 'a', 'c', 'b']);

$collection->duplicates();

// [2 => 'a', 4 => 'b']

もし、 collection が配列やオブジェクトを含んでいる場合、重複する values をチェックしたい attributes のキーを渡すことができます:

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

この method はduplicatesmethod と同じ signature を持っていますが、すべての"values"は"strict"比較を用いて比較されます。

`each()`

each method は collection のアイテムを順に処理し、各アイテムをクロージャに渡します：

$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 method は、collection のアイテムを反復処理し、各ネストされたアイテムの value を指定されたコールバックに渡します：

$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 method は、 collection のすべてのエレメントが指定された elements または type のリストであることを検証するために使用できます。そうでない場合、UnexpectedValueExceptionが throw されます：

return $collection->ensure(User::class);

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

string、int、float、bool、arrayのようなプリミティブ型も指定できます：

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

WARNING

ensure method は、異なる種類の elements が後から collection に追加されないことを保証しません。

`every()`

every method は、全ての collection の elements が指定された真偽 test を通過するかどうかを確認するために使用することができます：

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

// false

もし collection が空であるなら、every method は true を返します：

$collection = collect([]);

$collection->every(function (int $value, int $key) {
    return $value > 2;
});

// true

`except()`

except method は、指定された keys を持つものを除く、 collection 内のすべてのアイテムを返します。

$collection = collect(['product_id' => 1, 'price' => 100, 'discount' => false]);

$filtered = $collection->except(['price', 'discount']);

$filtered->all();

// ['product_id' => 1]

exceptの逆のために、onlyの method を参照してください。

NOTE

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

`filter()`

filter method は、指定したコールバックを使用して collection をフィルターし、指定した真偽 test を path した項目のみを保持します：

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

$filtered = $collection->filter(function (int $value, int $key) {
    return $value > 2;
});

$filtered->all();

// [3, 4]

コールバックが提供されていない場合、falseと等価な collection のすべてのエントリが削除されます：

$collection = collect([1, 2, 3, null, false, '', 0, []]);

$collection->filter()->all();

// [1, 2, 3]

filterの逆については、reject method を参照してください。

`first()`

first method は、指定の真偽 test を通過する collection の最初の要素を返します:

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

// 3

また、引数を指定せずにfirstの method を呼び出して collection の最初の要素を取得することもできます。もし collection が空の場合、nullが返されます。

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

// 1

`firstOrFail()`

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

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

// Throws ItemNotFoundException...

あなたはまた、 collection の最初の要素を取得するために引数なしでfirstOrFail method を呼び出すこともできます。 collection が空の場合、Illuminate\Support\ItemNotFoundExceptionの例外がスローされます。

collect([])->firstOrFail();

// Throws ItemNotFoundException...

`firstWhere()`

firstWhere method は、指定した key / value ペアを持つ collection の最初の要素を返します：

$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 method を呼び出すこともできます：

$collection->firstWhere('age', '>=', 18);

// ['name' => 'Diego', 'age' => 23]

where method のように、firstWhere method には 1 つの引数を渡すことができます。このシナリオでは、firstWhere method は、指定されたアイテムキーの value が "truthy" である最初のアイテムを返します:

$collection->firstWhere('age');

// ['name' => 'Linda', 'age' => 14]

`flatMap()`

flatMap method は、 collection を反復処理し、各 value を与えられたクロージャーに渡します。クロージャーは、要素を自由に変更して返し、これにより変更された項目の新たな collection が形成されます。その後、 array は 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の method は、多次元の collection を single の次元に平坦化します：

$collection = collect([
    'name' => 'taylor',
    'languages' => [
        'php', 'javascript'
    ]
]);

$flattened = $collection->flatten();

$flattened->all();

// ['taylor', 'php', 'javascript'];

必要に応じて、"depth" 引数を flatten method に渡すことができます：

$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 method は、collection の keys とそれに対応する values を入れ替えます：

$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);

$flipped = $collection->flip();

$flipped->all();

// ['taylor' => 'name', 'laravel' => 'framework']

`forget()`

forget method は、key によってアイテムを collection から削除します。

$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);

$collection->forget('name');

$collection->all();

// ['framework' => 'laravel']

WARNING

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

`forPage()`

forPage method は、指定されたページ番号に表示されるアイテムを含む新しい collection を返します。この method は、第 1 引数にページ番号を、第 2 引数にページごとの表示アイテム数を受け取ります：

$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9]);

$chunk = $collection->forPage(2, 3);

$chunk->all();

// [4, 5, 6]

`get()`

get method は指定されたキーにあるアイテムを返します。キーが存在しない場合、nullが返されます：

$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);

$value = $collection->get('name');

// taylor

オプションで、二番目の引数として default value を渡すことができます：

$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);

$value = $collection->get('age', 34);

// 34

あなたは、メソッドの default value としてコールバックを渡すことさえできます。指定されたキーが存在しない場合、コールバックの結果が返されます。

$collection->get('email', function () {
    return 'taylor@example.com';
});

// taylor@example.com

`groupBy()`

groupBy method は、指定されたキーによってコレクションのアイテムをグループ化します：

$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に string を渡す代わりに、コールバックを渡すことができます。コールバックは、グループ化するための value を返すべきです：

$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'],
        ],
    ]
*/

複数のグループ化基準は、 array として渡すことができます。各 array 要素は、多次元の array 内の対応するレベルに適用されます。

$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の method は、指定されたキーが collection 内に存在するかどうかを判断します：

$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 method は、指定された keys が collection 内に存在するかどうかを判断します。

$collection = collect(['account_id' => 1, 'product' => 'Desk', 'amount' => 5]);

$collection->hasAny(['product', 'price']);

// true

$collection->hasAny(['name', 'price']);

// false

`implode()`

implode"method は、collection のアイテムを結合します。その引数は、collection 内のアイテムの type に依存します。 collection が arrays または object を含む場合、属性の key を渡すべきです。結合したいものと、values の間に置きたい"glue"string：

$collection = collect([
    ['account_id' => 1, 'product' => 'Desk'],
    ['account_id' => 2, 'product' => 'Chair'],
]);

$collection->implode('product', ', ');

// Desk, Chair

もし collection がシンプルな文字列や数値の values を含む場合、"glue"を唯一の引数として method に渡すべきです：

collect([1, 2, 3, 4, 5])->implode('-');

// '1-2-3-4-5'

implode method に値の結合形式を指定したい場合、クロージャを渡すことができます：

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

// DESK, CHAIR

`intersect()`

intersect method は、与えられたarrayまたは collection に存在しないオリジナルの collection から任意の values を削除します。結果として得られる collection は、オリジナルコレクションの keys を維持します:

$collection = collect(['Desk', 'Sofa', 'Chair']);

$intersect = $collection->intersect(['Desk', 'Chair', 'Bookcase']);

$intersect->all();

// [0 => 'Desk', 2 => 'Chair']

NOTE

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

`intersectAssoc()`

intersectAssoc method は、元の collections と別の collection またはarrayを比較し、すべての与えられた collection に存在する key/ value のペアを返します。

$collection = collect([
    'color' => 'red',
    'size' => 'M',
    'material' => 'cotton'
]);

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

$intersect->all();

// ['size' => 'M']

`intersectByKeys()`

intersectByKeys method は、指定したarrayまたは collection に存在しない、元の collection から任意の keys およびそれに対応する values を削除します。

$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 method は、 collection が空の場合、trueを返します。それ以外の場合は、falseが返されます。

collect([])->isEmpty();

// true

`isNotEmpty()`

isNotEmpty method は、 collection が空でない場合、trueを返します。それ以外の場合は、falseが返されます。

collect([])->isNotEmpty();

// false

`join()`

join method は、collection の values を string に結合します。このメソッドの第二引数を使用して、最終要素が string にどのように追加されるべきかを指定することもできます。

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()`

keyBymethod は、指定された keys で collection を keys 指定します。複数のアイテムが同じ keys を持つ場合、新しい collection には最後のものだけが表示されます。

$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'],
    ]
*/

また、コールバックを method に渡すこともできます。コールバックは、 collection をキーとするための value を返すべきです：

$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 method は、コレクションのすべての 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 method は、与えられた真理 test を通過する collection の最後の要素を返します：

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

// 2

lastの method を引数なしで呼び出すことでも、 collection の最後の要素を取得することができます。もし collection が空であった場合は、nullが返されます。

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

// 4

`lazy()`

lazy method は、基になる array のアイテムから新しい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();

collection をLazyCollectionに変換することで、大量の追加メモリを割り当てる必要がなくなります。元の collection は依然としてその values をメモリに保持していますが、その後のフィルターはそうはなりません。したがって、コレクションの結果をフィルタリングする際に、ほとんど追加のメモリは割り当てられません。

`macro()`

静的な macro method により、実行時に Collection class にメソッドを追加することができます。詳しい情報は、collections の拡張に関するドキュメンテーションを参照してください。

`make()`

makeという静式の method は新たな collection のインスタンスを作成します。Collections 作成のセクションをご覧ください。

`map()`

map method は、 collection を反復処理し、各 value を与えられたコールバックに渡します。コールバックは、アイテムを自由に変更し、それを返すことができます。これにより、変更されたアイテムの新しい collection が形成されます。

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

WARNING

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

`mapInto()`

mapInto() method は、 collection を反復処理し、引数として value をコンストラクタに渡すことで指定された class の新しいインスタンスを作成します：

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 method はコレクションのアイテムを反復処理し、各ネストされたアイテムの value を指定されたクロージャに渡します。クロージャはアイテムを自由に変更し、それを返すことができます。これにより、変更されたアイテムの新しい collection が形成されます。

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

mapToGroupsmethod は、指定したクロージャによってコレクションのアイテムをグループ化します。クロージャは、シングルの key / values ペアを含む連想 array を返すべきであり、それにより新しい collection のグループ化された values を形成します：

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

mapWithKeysmethod は、collection を順に処理し、各 value を指定されたコールバックに渡します。コールバックは、単一の key / value ペアを含む連想 array を返す必要があります：

$collection = collect([
    [
        'name' => 'John',
        'department' => 'Sales',
        'email' => 'john@example.com',
    ],
    [
        'name' => 'Jane',
        'department' => 'Marketing',
        'email' => 'jane@example.com',
    ]
]);

$keyed = $collection->mapWithKeys(function (array $item, int $key) {
    return [$item['email'] => $item['name']];
});

$keyed->all();

/*
    [
        'john@example.com' => 'John',
        'jane@example.com' => 'Jane',
    ]
*/

`max()`

max method は、指定された key の最大の value を返します：

$max = collect([
    ['foo' => 10],
    ['foo' => 20]
])->max('foo');

// 20

$max = collect([1, 2, 3, 4, 5])->max();

// 5

`median()`

median method は、指定された key の中央値 value を返します：

$median = collect([
    ['foo' => 10],
    ['foo' => 10],
    ['foo' => 20],
    ['foo' => 40]
])->median('foo');

// 15

$median = collect([1, 1, 2, 4])->median();

// 1.5

`merge()`

merge method は与えられた array または collection を元の collection と merges します。与えられたアイテムの string key が元の collection の string key と一致する場合、与えられたアイテムの value は元の collection の value を上書きします：

$collection = collect(['product_id' => 1, 'price' => 100]);

$merged = $collection->merge(['price' => 200, 'discount' => false]);

$merged->all();

// ['product_id' => 1, 'price' => 200, 'discount' => false]

指定されたアイテムの keys が数値の場合、 values は collection の最後に追加されます。

$collection = collect(['Desk', 'Chair']);

$merged = $collection->merge(['Bookcase', 'Door']);

$merged->all();

// ['Desk', 'Chair', 'Bookcase', 'Door']

`mergeRecursive()`

mergeRecursivemethod は、与えられた array または collection を元の collection に再帰的に merges します。与えられた項目の stringkeys が元の collection の stringkeys と一致する場合、これらの keys の values は array に merges され、これが再帰的に行われます：

$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 method は与えられた key の最小の value を返します：

$min = collect([['foo' => 10], ['foo' => 20]])->min('foo');

// 10

$min = collect([1, 2, 3, 4, 5])->min();

// 1

`mode()`

mode method は与えられた key のモード valueを返します：

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

`nth()`

nth method は、n 番目の要素から構成される新しい collection を作成します:

$collection = collect(['a', 'b', 'c', 'd', 'e', 'f']);

$collection->nth(4);

// ['a', 'e']

必要に応じて、二番目の引数として開始オフセットを渡すことができます。

$collection->nth(4, 1);

// ['b', 'f']

`only()`

only method は、指定された keys を持つ collection 内のアイテムを返します：

$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の method を参照してください。

NOTE

このメソッドの振る舞いは、Eloquent Collectionsを使用すると変更されます。

`pad()`

pad method は、指定されたサイズに達するまで、与えられた value で array を埋めます。この method はarray_pad PHP 関数のように動作します。

左にパッドするには、サイズを負の数で指定する必要があります。指定されたサイズの絶対 value が array の length 以下の場合、パディングは行われません。

$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 method は PHP の array デストラクタリングと組み合わせて、与えられた真偽 test を通過する要素とそうでないものを分離することができます:

$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の method は、特定の真理テストに合格する collection 内のアイテムの割合を素早く決定するために使用できます:

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

$percentage = $collection->percentage(fn ($value) => $value === 1);

// 33.33

default で、パーセンテージは小数点以下 2 桁に丸められます。しかし、この動作は method に第二引数を提供することでカスタマイズすることができます：

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

// 33.333

`pipe()`

pipe method は与えられたクロージャに collection を渡し、実行されたクロージャの結果を返します。

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

$piped = $collection->pipe(function (Collection $collection) {
    return $collection->sum();
});

// 6

`pipeInto()`

pipeInto method は与えられた class の新しいインスタンスを作成し、そのコンストラクタに collection を渡します：

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 method は、指定された array のクロージャに collection を渡し、実行したクロージャの結果を返します：

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 method は、指定した key のすべての values を取得します：

$collection = collect([
    ['product_id' => 'prod-100', 'name' => 'Desk'],
    ['product_id' => 'prod-200', 'name' => 'Chair'],
]);

$plucked = $collection->pluck('name');

$plucked->all();

// ['Desk', 'Chair']

また、結果としての collection がどのようにキー付けされることを望んでいるか指定することもできます:

$plucked = $collection->pluck('name', 'product_id');

$plucked->all();

// ['prod-100' => 'Desk', 'prod-200' => 'Chair']

pluck method は、"dot"記法を使用してネストされた values を取得することもサポートしています：

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

重複する keys が存在する場合、最後の一致する要素が、取り出された collection に挿入されます：

$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 method は、 collection から最後のアイテムを削除し、返します。

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

$collection->pop();

// 5

$collection->all();

// [1, 2, 3, 4]

あなたはpopの method に integer を渡して、 collection の最後から複数のアイテムを削除し、返すことができます:

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

$collection->pop(3);

// collect([5, 4, 3])

$collection->all();

// [1, 2]

`prepend()`

prepend method は、アイテムを collection の先頭に追加します：

$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 method は、key によって collection からアイテムを削除し、返します：

$collection = collect(['product_id' => 'prod-100', 'name' => 'Desk']);

$collection->pull('name');

// 'Desk'

$collection->all();

// ['product_id' => 'prod-100']

`push()`

push method appends アイテムを collection の最後に追加します：

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

$collection->push(5);

$collection->all();

// [1, 2, 3, 4, 5]

`put()`

put method は、指定された key と value を collection に設定します：

$collection = collect(['product_id' => 1, 'name' => 'Desk']);

$collection->put('price', 100);

$collection->all();

// ['product_id' => 1, 'name' => 'Desk', 'price' => 100]

`random()`

random method は、collection からランダムな項目を返します：

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

$collection->random();

// 4 - (retrieved randomly)

randomに integer を渡して、ランダムに取得したいアイテムの数を指定することができます。希望するアイテムの数を明示的に渡すと、常に collection のアイテムが返されます。

$random = $collection->random(3);

$random->all();

// [2, 4, 5] - (retrieved randomly)

もし collection のインスタンスが要求されたアイテムよりも少なければ、random method はInvalidArgumentExceptionを throw します。

random method はクロージャも受け付けます。そこでは現在の collection インスタンスを受け取ります：

use Illuminate\Support\Collection;

$random = $collection->random(fn (Collection $items) => min(10, count($items)));

$random->all();

// [1, 2, 3, 4, 5] - (retrieved randomly)

`range()`

rangemethod は、指定された範囲内の整数を含む collection を返します：

$collection = collect()->range(3, 6);

$collection->all();

// [3, 4, 5, 6]

`reduce()`

reduce method は、 collection を single value に減らし、それぞれの反復の結果を次の反復に渡します。

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

$total = $collection->reduce(function (?int $carry, int $item) {
    return $carry + $item;
});

// 6

最初の反復での$carryの value はnullです。しかし、reduceに第二引数を渡すことで、その初期 value を指定することができます。

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

// 10

reduce method は、連想 collections の array keys も指定されたコールバックに渡します：

$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の method は、各イテレーションの結果を次のイテレーションに渡すことで、 collection を values の array に縮小します。この method はreduceメソッドに似ていますが、複数の初期 values を受け入れることができます。

[$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 method は与えられたクロージャを使って collection をフィルタリングします。アイテムが結果の collection から削除されるべきなら、クロージャはtrueを返すべきです。

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

$filtered = $collection->reject(function (int $value, int $key) {
    return $value > 2;
});

$filtered->all();

// [1, 2]

reject method の逆については、filter method を参照してください。

`replace()`

replace method はmergeと同様に動作します。ただし、string の string keys を持つ一致するアイテムを上書きするだけでなく、 replace method は、一致する数 values の keys を持つ collection 内のアイテムも上書きします。

$collection = collect(['Taylor', 'Abigail', 'James']);

$replaced = $collection->replace([1 => 'Victoria', 3 => 'Finn']);

$replaced->all();

// ['Taylor', 'Victoria', 'James', 'Finn']

`replaceRecursive()`

この method はreplaceのように動作しますが、配列に再帰的に作用し、内部の values に対して同じ process で置換を行います：

$collection = collect([
    'Taylor',
    'Abigail',
    [
        'James',
        'Victoria',
        'Finn'
    ]
]);

$replaced = $collection->replaceRecursive([
    'Charlie',
    2 => [1 => 'King']
]);

$replaced->all();

// ['Charlie', 'Abigail', ['James', 'King', 'Finn']]

`reverse()`

reverse method は、元の keys を保持したまま、collection の項目の順序を逆にします。

$collection = collect(['a', 'b', 'c', 'd', 'e']);

$reversed = $collection->reverse();

$reversed->all();

/*
    [
        4 => 'e',
        3 => 'd',
        2 => 'c',
        1 => 'b',
        0 => 'a',
    ]
*/

`search()`

search method は、指定された value を collection から検索し、見つかった場合はその key を返します。アイテムが見つからない場合、falseが返されます。

$collection = collect([2, 4, 6, 8]);

$collection->search(4);

// 1

検索"は"緩い"比較を使用して行われ、つまり "整数 value"を持つ"string"は同じ"value"の"整数"と等しく見なされます。厳密な比較を使用するには、二番目の引数にtrueを渡して"method"を使います：

collect([2, 4, 6, 8])->search('4', $strict = true);

// false

あるいは、指定された真実テストをパスする最初のアイテムを search するための自身のクロージャを提供してもかまいません：

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

// 2

`select()`

SELECT の method は、与えられた keys を collection から選択します。これは SQL の select statement に似ています。

$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 method は、 collection から最初のアイテムを削除し、返します：

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

$collection->shift();

// 1

$collection->all();

// [2, 3, 4, 5]

collection の開始部分から複数のアイテムを削除し、返すためにshift method に integer を渡すことができます：

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

$collection->shift(3);

// collect([1, 2, 3])

$collection->all();

// [4, 5]

`shuffle()`

shuffle method は、 collection 内のアイテムをランダムにシャッフルします：

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

$shuffled = $collection->shuffle();

$shuffled->all();

// [3, 2, 5, 1, 4] - (generated randomly)

`skip()`

skip method は、指定された数の elements を collection の先頭から削除した新しい collection を返します：

$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 method は、指定されたコールバックがtrueを返すまで、 collection からの項目をスキップします。そして、新しい collection インスタンスとして、 collection 内の残りの項目を返します。

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

$subset = $collection->skipUntil(function (int $item) {
    return $item >= 3;
});

$subset->all();

// [3, 4]

また、skipUntil method に単純な value を渡して、指定された value が見つかるまですべてのアイテムを skip することもできます。

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

$subset = $collection->skipUntil(3);

$subset->all();

// [3, 4]

WARNING

もし与えられた value が見つからない、またはコールバックがtrueを返さない場合、skipUntil method は空の collection を返します。

`skipWhile()`

skipWhile method は、指定されたコールバックがtrueを返す間、 collection のアイテムをスキップし、その後、 collection の残りのアイテムを新しい collection として返します:

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

$subset = $collection->skipWhile(function (int $item) {
    return $item <= 3;
});

$subset->all();

// [4]

WARNING

コールバックがfalseを返さない場合、skipWhile method は空の collection を返します。

`slice()`

slice method は、指定されたインデックスから collection のスライスを返します:

$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);

$slice = $collection->slice(4);

$slice->all();

// [5, 6, 7, 8, 9, 10]

返されるスライスのサイズを制限したい場合は、所望のサイズを method の第 2 引数として渡してください：

$slice = $collection->slice(4, 2);

$slice->all();

// [5, 6]

返されるスライスは、 default で keys を保持します。元の keys を保持したくない場合は、values method を使用してそれらを再インデックスすることができます。

`sliding()`

sliding method は、collection 内のアイテムの"sliding window" view を表す新しい collection のチャンクを返します：

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

$chunks = $collection->sliding(2);

$chunks->toArray();

// [[1, 2], [2, 3], [3, 4], [4, 5]]

これは特に、eachSpread method と組み合わせると非常に便利です：

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

オプションで、2 番目の "step" value を渡すこともできます。これは、すべての chunk の最初のアイテム間の距離を決定します。

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

$chunks = $collection->sliding(3, step: 2);

$chunks->toArray();

// [[1, 2, 3], [3, 4, 5]]

`sole()`

soleの method は、指定された真偽テストをクリアする collection の最初の要素を返しますが、真偽テストが正確に 1 つの要素に一致する場合に限ります：

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

// 2

また、key/ value ペアを sole method に渡すこともできます。これにより、指定されたペアに一致する collection の最初の要素が返されますが、一致する要素が正確に一つだけの場合のみです。

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

$collection->sole('product', 'Chair');

// ['product' => 'Chair', 'price' => 100]

あるいは、 collection 内の最初の要素を取得するために、引数なしで sole method を呼び出すこともできます。ただし、これは要素が 1 つだけの場合に限ります：

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

$collection->sole();

// ['product' => 'Desk', 'price' => 200]

sole method が返すべき collection 内にエレメントがない場合、\Illuminate\Collections\ItemNotFoundException 例外が throw されます。返されるべきエレメントが一つ以上ある場合、\Illuminate\Collections\MultipleItemsFoundException 例外が throw されます。

`some()`

contains method の別名です。

`sort()`

sort method は、 collection を並べ替えます。並べ替えられた collection は元の array keys を保持するため、次の例では、values method を使用して keys を連続した番号のインデックスに reset します:

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

$sorted = $collection->sort();

$sorted->values()->all();

// [1, 2, 3, 4, 5]

もし、あなたのソートニーズがより高度なものである場合、独自の algorithm を用いてsortにコールバックを渡すことができます。コレクションの sort method が内部で使用するuasort についての PHP ドキュメンテーションを参照してください。

NOTE

ネストされた配列やオブジェクトの collection をソートする必要がある場合は、sortBy メソッドと sortByDesc メソッドをご覧ください。

`sortBy()`

sortBy method は与えられた keys によって collection を並べ替えます。並べ替えられた collection は元の array の keys を保持するため、以下の例ではvalues method を使って keys を連続的な番号のインデックスに reset します：

$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 method は、その第二引数としてソートフラグを受け入れます：

$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'],
    ]
*/

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

$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']],
    ]
*/

もし複数の属性によってあなたの collection をソートしたい場合は、ソート操作の array を sortBy method に渡すことができます。各ソート操作は、ソートしたい属性と所望のソート方向を含む array であるべきです:

$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],
    ]
*/

複数の attributes で collection を並べ替えるとき、各ソート操作を定義するクロージャを提供することもできます:

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

この method は、sortByの method と同じ signature を持っていますが、 collection を逆の順序でソートします。

`sortDesc()`

この method は、sort method とは逆の順序で collection を並べ替えます：

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

$sorted = $collection->sortDesc();

$sorted->values()->all();

// [5, 4, 3, 2, 1]

sortとは異なり、クロージャをsortDescに渡すことはできません。代わりに、sort method を使用し、比較を反転させるべきです。

`sortKeys()`

sortKeys method は、基礎となる連想 array の keys によって collection を並び替えます：

$collection = collect([
    'id' => 22345,
    'first' => 'John',
    'last' => 'Doe',
]);

$sorted = $collection->sortKeys();

$sorted->all();

/*
    [
        'first' => 'John',
        'id' => 22345,
        'last' => 'Doe',
    ]
*/

`sortKeysDesc()`

この method はsortKeysの method と同じ signature を持ちますが、逆の順序で collection を並べ替えます。

`sortKeysUsing()`

sortKeysUsing method は、コールバックを使用して、基礎となる連想 array の keys により collection をソートします：

$collection = collect([
    'ID' => 22345,
    'first' => 'John',
    'last' => 'Doe',
]);

$sorted = $collection->sortKeysUsing('strnatcasecmp');

$sorted->all();

/*
    [
        'first' => 'John',
        'ID' => 22345,
        'last' => 'Doe',
    ]
*/

コールバックは、ゼロ以下、ゼロと等しい、またはゼロより大きい整数を返す比較関数でなければなりません。詳細は、sortKeysUsingmethod が内部で利用する PHP 関数であるuksort に関する PHP のドキュメンテーションを参照してください。

`splice()`

splice method は、指定されたインデックスから始まるアイテムのスライスを削除し、返します：

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

$chunk = $collection->splice(2);

$chunk->all();

// [3, 4, 5]

$collection->all();

// [1, 2]

結果の collection のサイズを制限するために、2 番目の引数を渡すことができます。

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

$chunk = $collection->splice(2, 1);

$chunk->all();

// [3]

$collection->all();

// [1, 2, 4, 5]

さらに、削除された collection のアイテムを置き換える新しいアイテムを含む第三の引数を渡すことができます：

$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 method は、指定された数のグループに collection を分割します：

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

$groups = $collection->split(3);

$groups->all();

// [[1, 2], [3, 4], [5]]

`splitIn()`

splitIn method は、与えられた数のグループに collection を分割し、最終グループに残りを割り当てる前に非終端グループを完全に埋めます：

$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 method は、 collection 内のすべてのアイテムの合計を返します。

collect([1, 2, 3, 4, 5])->sum();

// 15

collection にネストされた配列やオブジェクトが含まれている場合、どの values を合計するかを決定するために使用されるキーを渡すべきです：

$collection = collect([
    ['name' => 'JavaScript: The Good Parts', 'pages' => 176],
    ['name' => 'JavaScript: The Definitive Guide', 'pages' => 1096],
]);

$collection->sum('pages');

// 1272

また、どの collection の values を合計するかを決定するための独自のクロージャを渡すこともできます：

$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 method は、指定された数のアイテムを持つ新しい collection を返します：

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

$chunk = $collection->take(3);

$chunk->all();

// [0, 1, 2]

また、指定した数のアイテムを collection の最後から取得するために、負の integer を渡すこともできます：

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

$chunk = $collection->take(-2);

$chunk->all();

// [4, 5]

`takeUntil()`

takeUntil method は、指定されたコールバックがtrueを返すまでの collection 内のアイテムを返します。

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

$subset = $collection->takeUntil(function (int $item) {
    return $item >= 3;
});

$subset->all();

// [1, 2]

また、takeUntilの method に単純な value を渡して、指定された value が見つかるまでの項目を取得することもできます：

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

$subset = $collection->takeUntil(3);

$subset->all();

// [1, 2]

WARNING

指定された value が見つからないか、コールバックがtrueを返さない場合、takeUntil method は collection 内のすべてのアイテムを返します。

`takeWhile()`

takeWhile method は、指定されたコールバックがfalseを返すまで、 collection 内のアイテムを返します：

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

$subset = $collection->takeWhile(function (int $item) {
    return $item < 3;
});

$subset->all();

// [1, 2]

WARNING

コールバックがfalseを返さない場合、takeWhile method は collection 内のすべてのアイテムを返します。

`tap()`

tap "" method "" は "" collection "" を指定したコールバックに渡し、ある特定の点で "" collection "" に"タップ"して、アイテムを操作しながら "" collection "" 自体に影響を与えません。そして、"" collection "" は tap "" method "" によって返されます。

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

// 1

`times()`

静的な times の method は、指定された回数だけ与えられたクロージャを呼び出すことで新しい collection を作成します：

$collection = Collection::times(10, function (int $number) {
    return $number * 9;
});

$collection->all();

// [9, 18, 27, 36, 45, 54, 63, 72, 81, 90]

`toArray()`

toArray method は collection をプレーンな PHP array に変換します。もしコレクションの values がEloquent models であれば、models も arrays に変換されます：

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

$collection->toArray();

/*
    [
        ['name' => 'Desk', 'price' => 200],
    ]
*/

WARNING

toArrayは、Arrayableのインスタンスであるコレクションのすべてのネストされた objects も array に変換します。 collection の下にある原始的な array を取得したい場合は、代わりにall method を使用してください。

`toJson()`

toJson method は、 collection を JSON シリアライズされた string に変換します。

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

$collection->toJson();

// '{"name":"Desk", "price":200}'

`transform()`

transform method は、collection 上を反復処理し、各アイテムに対して指定したコールバックを呼び出します。collection のアイテムは、コールバックによって返された values に置き換えられます。

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

$collection->transform(function (int $item, int $key) {
    return $item * 2;
});

$collection->all();

// [2, 4, 6, 8, 10]

WARNING

ほとんどの他の collection メソッドとは異なり、 transformは collection 自体を変更します。代わりに新しい collection を作成したい場合は、map method を使用してください。

`undot()`

undot"の method は、"dot"表記法を使用した単一次元の collection を、多次元の collection に展開します：

$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 method は与えられた array を collection に追加します。もし与えられた array が既にオリジナルの collection に存在する keys を含んでいる場合、オリジナルの collection の values が優先されます。

$collection = collect([1 => ['a'], 2 => ['b']]);

$union = $collection->union([3 => ['c'], 1 => ['d']]);

$union->all();

// [1 => ['a'], 2 => ['b'], 3 => ['c']]

`unique()`

uniqueの method は、 collection 内のすべての unique なアイテムを返します。返される collection は元の array keys を保持しているので、次の例ではvaluesの method を使用して、 keys を連続した数値のインデックスに reset します。

$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'],
    ]
*/

最後に、アイテムの一意性を決定するべき value を指定するために、独自のクロージャをunique method に渡すことも可能です：

$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の method はアイテムの values をチェックする際に"ゆるい"比較を使用します。つまり、 integer value を持つ string は同じ value の integer と等しいと考えられます。 "厳格な"比較を使用してフィルタリングするためには、uniqueStrictの method を使用してください。

NOTE

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

`uniqueStrict()`

この method は、unique method 同じ signature を持っています。ただし、全ての values は、"strict" comparisons で比較されます。

`unless()`

unlessmethod は、与えられたコールバックを実行します。ただし、method へ与えられた最初の引数が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 method に渡すことができます。二つ目のコールバックは、unless method に与えられた最初の引数がtrueに評価された時に実行されます。

$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 method を参照してください。

`unlessEmpty()`

whenNotEmpty method の別名。

`unlessNotEmpty()`

whenEmpty method のエイリアス。

`unwrap()`

静的な unwrap method は、適用可能な場合、指定された value から collection の基本的なアイテムを返します:

Collection::unwrap(collect('John Doe'));

// ['John Doe']

Collection::unwrap(['John Doe']);

// ['John Doe']

Collection::unwrap('John Doe');

// 'John Doe'

`value()`

value method は、指定された value を collection の最初の要素から取得します。

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

$value = $collection->value('price');

// 200

`values()`

values method は、keys の reset を連続する整数にした新しい collection を返します。

$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 method は、与えられた引数がtrueと評価された時に、指定されたコールバックを実行します。 collection インスタンスとwhen method に与えられた最初の引数はクロージャーに渡されます。

$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の method には、2 つ目のコールバックを渡すことができます。2 つ目のコールバックは、whenの method に与えられた最初の引数がfalseと評価されたときに実行されます。

$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の method を参照してください。

`whenEmpty()`

whenEmpty method は、 collection が空の場合に指定されたコールバックを実行します：

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

二番目のクロージャは whenEmpty method に渡すことができ、そのクロージャは collection が空でない場合に実行されます：

$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 method をご覧ください。

`whenNotEmpty()`

whenNotEmpty method は、 collection が空でない場合に指定されたコールバックを実行します：

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

// []

二番目のクロージャは、whenNotEmpty method に渡すことができ、これは collection が空の場合に実行されます。

$collection = collect();

$collection->whenNotEmpty(function (Collection $collection) {
    return $collection->push('adam');
}, function (Collection $collection) {
    return $collection->push('taylor');
});

$collection->all();

// ['taylor']

whenNotEmptyの逆については、whenEmpty method を参照してください。

`where()`

where method は、与えられた key/ value のペアによって collection をフィルタリングします：

$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],
    ]
*/

wheremethod は、アイテムの values をチェックする際に"ルーズ"な比較を使用します。つまり、整数値を持つ string は、同じ values を持つ整数と同等とみなされます。"厳密"な比較を使用してフィルタリングするには、whereStrict method を使用してください。

オプションとして、比較演算子を第二パラメータとして渡すこともできます。対応している演算子は次の通りです：'===', '!==', '!=', '==', '=', '<>', '>', '<', '>=', '<=':

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

この method は、whereメソッドと同じ signature を持っています。ただし、すべての values は"strict"な比較を使用して比較されます。

`whereBetween()`

whereBetween method は、指定されたアイテムの value が与えられた範囲内にあるかどうかを判断することで、 collection をフィルタリングします。

$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 method は、指定されたアイテムの value が与えられた array 内に含まれていない elements を collection から削除します。

$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の method はアイテムの values をチェックする際にゆるい比較を使用します。つまり、整数 values を持つ string は同じ values の整数と同等とみなされます。厳密な比較を使用してフィルタリングするには、whereInStrictの method を使用します。

`whereInStrict()`

この method は、whereInメソッドと同じ signature を持っています。ただし、すべての values は strict な比較を使用して比較されます。

`whereInstanceOf()`

whereInstanceOf method は指定された class type によって collection をフィルタリングします：

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 method は、特定のアイテムの value が指定した範囲外であるかどうかを判断することで、 collection をフィルタリングします：

$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 method は、指定されたアイテムの value が与えられた array 内に含まれている collection から elements を削除します。

$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の method は、アイテムの values をチェックする際にルーズな比較を使います。つまり、整数 values を持つ string は、同じ values の整数と等しいと見なされるでしょう。strict な比較を使用してフィルタリングするには、whereNotInStrict の method を使ってください。

`whereNotInStrict()`

この method は、whereNotInメソッドと同じ signature を持ちます。ただし、全ての values は strict な比較を用いて比較されます。

`whereNotNull()`

whereNotNull method は、指定された key がnullでない場合に、 collection からアイテムを返します。

$collection = collect([
    ['name' => 'Desk'],
    ['name' => null],
    ['name' => 'Bookcase'],
]);

$filtered = $collection->whereNotNull('name');

$filtered->all();

/*
    [
        ['name' => 'Desk'],
        ['name' => 'Bookcase'],
    ]
*/

`whereNull()`

whereNull method は、指定された key がnullの場合、 collection からアイテムを返します。

$collection = collect([
    ['name' => 'Desk'],
    ['name' => null],
    ['name' => 'Bookcase'],
]);

$filtered = $collection->whereNull('name');

$filtered->all();

/*
    [
        ['name' => null],
    ]
*/

`wrap()`

静的な wrap method は、該当する場合に与えられた value を collection でラップします。

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 method は、与えられた array の values と元の collection の values をそれぞれのインデックスで結合します：

$collection = collect(['Chair', 'Desk']);

$zipped = $collection->zip([100, 200]);

$zipped->all();

// [['Chair', 100], ['Desk', 200]]

Higher Order Messages

collections は、Higher Order Messages と呼ばれる機能もサポートしており、これは collections に対する一般的な操作を短縮するためのものです。高階メッセージを提供する collections の methods は、次のとおりです：average、avg、contains、each、every、filter、first、flatMap、groupBy、keyBy、map、max、min、partition、reject、skipUntil、skipWhile、some、sortBy、sortByDesc、sum、takeUntil、takeWhile、そしてuniqueです。

各高次メッセージは、 collection インスタンスの動的プロパティとしてアクセスすることができます。例えば、each 高次メッセージを使用して、 collection 内の各 object 上の method を呼び出しましょう：

use App\Models\User;

$users = User::where('votes', '>', 500)->get();

$users->each->markAsVip();

同様に、sum の高階メッセージを使用して、 collection の users の投票の総数を集計することができます：

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

return $users->sum->votes;

Lazy Collections

Introduction

WARNING

Laravel の lazy collections について詳しく学ぶ前に、PHP generators に慣れる時間を少し取ってください。

既に強力なCollection class を補完するために、LazyCollection class は PHP のジェネレータを利用して、非常に大きな data セットを低いメモリ使用量で操作できるようにします。

例えば、あなたの application がマルチギガバイトの log ファイルを process する必要があると想像してみてください。ログをパースするために Laravel の collection メソッドを活用しながら、ファイル全体を一度にメモリに読み込むのではなく、 lazy collections を使用して、一度にメモリに保持するファイルの一部を小さくすることができます。

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 models を反復する必要があると想像してみてください。従来の Laravel collections を使用すると、すべての 10,000 の Eloquent models が同時にメモリにロードされる必要があります：

use App\Models\User;

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

しかし、 query ビルダーの cursor method は LazyCollection インスタンスを返します。これにより、まだ database に対して single query を実行できるだけでなく、一度にメモリにロードできる Eloquent model も 1 つだけにすることができます。この例では、 filter コールバックは、それぞれの user を実際に個々に反復処理するまで実行されません、これによりメモリ使用量を大幅に削減することができます。

use App\Models\User;

$users = User::cursor()->filter(function (User $user) {
    return $user->id > 500;
});

foreach ($users as $user) {
    echo $user->id;
}

Lazy Collections の作成

lazy collection インスタンスを作成するには、PHP ジェネレーター関数をコレクションの make method に渡す必要があります：

use Illuminate\Support\LazyCollection;

LazyCollection::make(function () {
    $handle = fopen('log.txt', 'r');

    while (($line = fgets($handle)) !== false) {
        yield $line;
    }
});

Enumerable 契約

ほとんどすべてのCollection class で利用可能な methods は、LazyCollection class でも利用可能です。これら両方のクラスはIlluminate\Support\Enumerable契約を実装しており、以下の methods を定義しています：

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

WARNING

collection を変更する Methods(shift、pop、prepend etc )は、LazyCollection class では利用できません。

Lazy Collection メソッド

Enumerable契約で定義されたメソッドに加えて、LazyCollection class には以下のメソッドが含まれています：

`takeUntilTimeout()`

takeUntilTimeout method は、指定時間まで values を列挙する新しい lazy collection を返します。その時間の後、 collection は列挙を停止します。

$lazyCollection = LazyCollection::times(INF)
    ->takeUntilTimeout(now()->addMinute());

$lazyCollection->each(function (int $number) {
    dump($number);

    sleep(1);
});

// 1
// 2
// ...
// 58
// 59

この method の使用法を説明するために、請求書を database から cursor を使用して送信する application を想像してみてください。 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の method は与えられたコールバックを collection の各アイテムに対して直ちに呼び出しますが、tapEachの method はアイテムがリストから一つずつ取り出されるときのみ与えられたコールバックを呼び出します。

// 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 の method は、指定された秒数ごとにそれぞれの value が返されるように、 lazy collection を throttle します。この method は、受信リクエストをレート制限する外部 API とやり取りをする可能性がある状況で特に役立ちます:

use App\Models\User;

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

`remember()`

remember method は、すでに列挙された values を記憶して、次回の collection の列挙で再度取得しない新しい lazy collection を返します。

// 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();