コレクション

はじめに

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 を介してアクセスでき、まるでコレクションクラスの実際のメソッドであるかのように振る舞います。たとえば、次のコードは Collection クラスに toUpper メソッドを追加します。

    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 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(['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 メソッドは、指定された配列やコレクションの間でコレクションの値をクロス結合し、すべての可能な順列を持つデカルト積を返します：

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

コールバックは、0より小さい、等しい、または0より大きい整数を返す比較関数でなければなりません。詳細については、diffAssocUsingメソッドが内部で利用するPHP関数であるarray_diff_uassocの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' => 'abigail@example.com', 'position' => 'Developer'],
        ['email' => 'james@example.com', 'position' => 'Designer'],
        ['email' => 'victoria@example.com', 'position' => 'Developer'],
    ]);

    $employees->duplicates('position');

    // [2 => 'Developer']

`duplicatesStrict()`

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

`each()`

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

    $collection = 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 メソッドは、指定されたアイテムキーの値が "truthy" である最初のアイテムを返します：

    $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 メソッドに "depth" 引数を渡すことができます：

    $collection = collect([
        'Apple' => [
            [
                'name' => 'iPhone 6S',
                'brand' => 'Apple'
            ],
        ],
        'Samsung' => [
            [
                'name' => 'Galaxy S7',
                'brand' => 'Samsung'
            ],
        ],
    ]);

    $products = $collection->flatten(1);

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

    /*
        [
            ['name' => 'iPhone 6S', 'brand' => 'Apple'],
            ['name' => 'Galaxy S7', 'brand' => 'Samsung'],
        ]
    */

この例では、flatten を深さを指定せずに呼び出すと、ネストされた配列もフラット化され、['iPhone 6S', 'Apple', 'Galaxy S7', 'Samsung'] となります。深さを指定することで、ネストされた配列がフラット化されるレベルの数を指定できます。

`flip()`

flip メソッドはコレクションのキーとそれに対応する値を入れ替えます：

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

    $flipped = $collection->flip();

    $flipped->all();

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

`forget()`

forget メソッドはキーによってコレクションからアイテムを削除します：

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

    $collection->forget('name');

    $collection->all();

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

警告

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

`forPage()`

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

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

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

    $chunk->all();

    // [4, 5, 6]

get メソッドは指定されたキーのアイテムを返します。キーが存在しない場合は null が返されます:

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

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

    // taylor

2 番目の引数としてデフォルト値をオプションで渡すことができます:

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

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

    // 34

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

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

    // taylor@example.com

`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 メソッドはコレクション内のアイテムを結合します。引数はコレクション内のアイテムの種類に依存します。コレクションに配列やオブジェクトが含まれている場合は、結合したい属性のキーと、値の間に配置したい "glue" 文字列を渡す必要があります:

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

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

    // Desk, Chair

コレクションに単純な文字列や数値が含まれている場合は、"glue" をメソッドの唯一の引数として渡す必要があります:

    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 メソッドは、コレクションの値を文字列で結合します。このメソッドの第2引数を使用して、最終要素を文字列に追加する方法を指定することもできます：

    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' => '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メソッドは、指定されたキーの最大値を返します：

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

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

先頭に追加されるアイテムのキーを指定するために、第二引数を渡すこともできます：

    $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

検索は「緩い」比較を使用して行われ、つまり整数値を持つ文字列は同じ値の整数と等しいと見なされます。「厳密な」比較を使用するには、メソッドの第2引数として true を渡します：

    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]

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

    $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 例外がスローされます。返すべき要素が複数ある場合、\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 より小さい整数、0、または 0 より大きい整数を返す比較関数である必要があります。詳細については、sortKeysUsing メソッドが内部で利用する PHP 関数である uksort の PHP ドキュメントを参照してください。

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

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

    $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 に評価される場合に、unless メソッドに渡された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メソッドには、第二引数として別のコールバックを渡すこともできます。whenメソッドに渡された最初の引数が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メソッドを参照してください。

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

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

    // []

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メソッドを使用してください。

オプションで、第二引数として比較演算子を渡すことができます。サポートされる演算子は、'===', '!==', '!=', '==', '=', '<>', '>', '<', '>=', および '<='です：

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

ハイアーオーダーメッセージ

コレクションは、"ハイアーオーダーメッセージ"をサポートしており、コレクション上で一般的なアクションを実行するためのショートカットを提供します。ハイアーオーダーメッセージを提供するコレクションメソッドは、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ハイアーオーダーメッセージを使用して、ユーザーコレクションの合計"votes"数を集計することができます：

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

    return $users->sum->votes;

遅延コレクション

はじめに

警告

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...
    });

また、1万のEloquentモデルを反復処理する必要があるとします。従来のLaravelコレクションを使用すると、1万のEloquentモデル全体が同時にメモリにロードされる必要があります：

    use App\Models\User;

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

しかし、クエリビルダーの cursor メソッドは LazyCollection インスタンスを返します。これにより、データベースに対しては引き続き単一のクエリのみが実行されますが、一度に1つのEloquentモデルのみがメモリにロードされます。この例では、filter コールバックは、実際に各ユーザーを個別に反復処理するまで実行されません。これにより、メモリ使用量が劇的に削減されます：

    use App\Models\User;

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

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

遅延コレクションの作成

遅延コレクションインスタンスを作成するには、コレクションの make メソッドにPHPジェネレータ関数を渡す必要があります：

    use Illuminate\Support\LazyCollection;

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

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

Enumerable契約

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 クラスでは利用できません。

遅延コレクションのメソッド

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 メソッドは、既に列挙された値を覚えておき、後続のコレクション列挙時に再取得しない新しい遅延コレクションを返します:

    // まだクエリは実行されていません...
    $users = User::cursor()->remember();

    // クエリが実行されます...
    // 最初の5人のユーザーがデータベースから取得されます...
    $users->take(5)->all();

    // 最初の5人のユーザーはコレクションのキャッシュから取得されます...
    // 残りはデータベースから取得されます...
    $users->take(20)->all();

コレクション

はじめに​

コレクションの作成​

コレクションの拡張​

マクロ引数​

利用可能なメソッド​

メソッドリスト​

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

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

はじめに

コレクションの作成

コレクションの拡張

マクロ引数

利用可能なメソッド

メソッドリスト

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

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