Laravel 8.x コレクション

イントロダクションIntroduction

Illuminate\Support\Collectionクラスは配列データを操作するための、書きやすく使いやすいラッパーです。以下の例をご覧ください。配列から新しいコレクションインスタンスを作成するためにcollectヘルパを使用し、各要素に対しstrtoupperを実行し、それから空の要素を削除しています。The Illuminate\Support\Collection class provides a fluent, convenient wrapper for working with arrays of data. For example, check out the following code. We'll use the collect helper to create a new collection instance from the array, run the strtoupper function on each element, and then remove all empty elements:

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

ご覧の通り、Collectionクラスは裏にある配列をマップ操作してから要素削除するメソッドをチェーンでスムーズにつなげてくれます。つまり元のコレクションは不変であり、すべてのCollectionメソッドは新しいCollectionインスタンスを返します。As you can see, the Collection class allows you to chain its methods to perform fluent mapping and reducing of the underlying array. In general, collections are immutable, meaning every Collection method returns an entirely new Collection instance.

コレクション生成Creating Collections

上記の通りcollectヘルパは指定された配列を元に、新しいIlluminate\Support\Collectionインスタンスを返します。ですからコレクションの生成も同様にシンプルです。As mentioned above, the collect helper returns a new Illuminate\Support\Collection instance for the given array. So, creating a collection is as simple as:

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

lightbulb">Tip!! Eloquentクエリの結果は、常にCollectionインスタンスを返します。{tip} The results of Eloquent[/docs/{{version}}/eloquent] queries are always returned as Collection instances.

コレクションの拡張Extending Collections

コレクションは「マクロ化可能」であり、実行時にCollectionクラスへメソッドを追加できます。Illuminate\Support\Collectionクラスのmacroメソッドは、マクロが呼び出されたときに実行するクロージャを引数に取ります。マクロクロージャは、コレクションクラスの実際のメソッドであるかのように、$thisを介してコレクションの他のメソッドにアクセスできます。たとえば、次のコードは、toUpperメソッドをCollectionクラスに追加しています。Collections are "macroable", which allows you to add additional methods to the Collection class at run time. The Illuminate\Support\Collection class' macro method accepts a closure that will be executed when your macro is called. The macro closure may access the collection's other methods via $this, just as if it were a real method of the collection class. For example, the following code adds a toUpper method to the Collection class:

use Illuminate\Support\Collection;
use Illuminate\Support\Str;

Collection::macro('toUpper', function () {
    return $this->map(function ($value) {
        return Str::upper($value);
    });
});

$collection = collect(['first', 'second']);

$upper = $collection->toUpper();

// ['FIRST', 'SECOND']

通常、コレクションマクロはサービスプロバイダのbootメソッドで宣言する必要があります。Typically, you should declare collection macros in the boot method of a service provider[/docs/{{version}}/providers].

マクロ引数Macro Arguments

必要に応じて、追加の引数を取るマクロを定義できます。If necessary, you may define macros that accept additional arguments:

use Illuminate\Support\Collection;
use Illuminate\Support\Facades\Lang;

Collection::macro('toLocale', function ($locale) {
    return $this->map(function ($value) use ($locale) {
        return Lang::get($value, [], $locale);
    });
});

$collection = collect(['first', 'second']);

$translated = $collection->toLocale('es');

利用可能なメソッドAvailable Methods

コレクションドキュメントの残りの大部分は、Collectionクラスで使用できる各メソッドについて説明します。これらのメソッドはすべて、基になる配列をスムースに操作するためチェーン化できることを忘れないでください。さらに、ほとんどすべてのメソッドが新しいCollectionインスタンスを返すため、必要に応じて元のコレクションを保持できます。For the majority of the remaining collection documentation, we'll discuss each method available on the Collection class. Remember, all of these methods may be chained to fluently manipulate the underlying array. Furthermore, almost every method returns a new Collection instance, allowing you to preserve the original copy of the collection when necessary:

メソッド一覧Method Listing

all() all()

allメソッドはコレクションの裏の配列表現を返します。The all method returns the underlying array represented by the collection:

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

// [1, 2, 3]

average() average()

avgメソッドのエイリアスです。Alias for the avg[#method-avg] method.

avg() avg()

avgメソッドは、指定したキーの平均値を返します。The avg method returns the average value[https://en.wikipedia.org/wiki/Average] of a given key:

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

// 20

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

// 2

chunk() chunk()

chunkメソッドはコレクションを指定したサイズで複数の小さなコレクションに分割します。The chunk method breaks the collection into multiple, smaller collections of a given size:

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

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

$chunks->all();

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

このメソッドは、Bootstrapなどのグリッドシステムを操作するときにビューで特に役立ちます。たとえば、グリッドに表示するEloquentモデルのコレクションがあるとします。This method is especially useful in views[/docs/{{version}}/views] when working with a grid system such as Bootstrap[https://getbootstrap.com/docs/4.1/layout/grid/]. For example, imagine you have a collection of Eloquent[/docs/{{version}}/eloquent] models you want to display in a grid:

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

chunkWhileメソッドは、指定したコールバックの評価に基づいて、コレクションを複数のより小さなコレクションへ分割します。クロージャに渡された$chunk変数は、前の要素を検査するために使用できます。The chunkWhile method breaks the collection into multiple, smaller collections based on the evaluation of the given callback. The $chunk variable passed to the closure may be used to inspect the previous element:

$collection = collect(str_split('AABBCCCD'));

$chunks = $collection->chunkWhile(function ($value, $key, $chunk) {
    return $value === $chunk->last();
});

$chunks->all();

// [['A', 'A'], ['B', 'B'], ['C', 'C', 'C'], ['D']]

collapse() collapse()

collapseメソッドは、配列のコレクションをフラットな一次コレクションに展開します。The collapse method collapses a collection of arrays into a single, flat 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()

collectメソッドは、コレクション中の現在のアイテムを利用した、新しいCollectionインスタンスを返します。The collect method returns a new Collection instance with the items currently in the collection:

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

$collectionB = $collectionA->collect();

$collectionB->all();

// [1, 2, 3]

collectメソッドは、レイジーコレクションを通常のCollectionインスタンスへ変換するのにとくに便利です。The collect method is primarily useful for converting lazy collections[#lazy-collections] into standard Collection instances:

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

$collection = $lazyCollection->collect();

get_class($collection);

// 'Illuminate\Support\Collection'

$collection->all();

// [1, 2, 3]

lightbulb">Tip!! collectメソッドはEnumerableのインスタンスがあり、それをレイジーコレクションでなくする必要がある場合、とくに便利です。collect()はEnumerable契約の一部であり、Collectionインスタンスを取得するため安全に使用できます。{tip} The collect method is especially useful when you have an instance of Enumerable and need a non-lazy collection instance. Since collect() is part of the Enumerable contract, you can safely use it to get a Collection instance.

combine() combine()

combineメソッドは、コレクションの値をキーとして、他の配列かコレクションの値を結合します。The combine method combines the values of the collection, as keys, with the values of another array or collection:

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

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

$combined->all();

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

concat() concat()

concatメソッドは、指定したarrayまたはコレクションの値を別のコレクションの最後に追加します。The concat method appends the given array or collection's values onto the end of another collection:

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

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

$concatenated->all();

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

contains() contains()

containsメソッドは、コレクションに指定したアイテムが含まれているか判定します。指定する真偽判定にマッチする要素がコレクション内に存在するかを判定するために、containsメソッドにクロージャを渡します。The contains method determines whether the collection contains a given item. You may pass a closure to the contains method to determine if an element exists in the collection matching a given truth test:

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

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

// false

または、文字列をcontainsメソッドに渡して、コレクションに指定アイテム値が含まれているかどうかを判断することもできます。Alternatively, you may pass a string to the contains method to determine whether the collection contains a given item value:

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

$collection->contains('Desk');

// true

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

// false

さらにcontainsメソッドにはキー／値ペアを指定することもでき、コレクション中に指定したペアが存在するかを確認できます。You may also pass a key / value pair to the contains method, which will determine if the given pair exists in the collection:

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

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

// false

containsメソッドは、アイテムを「緩く」比較します。つまり、ある整数の文字列とその整数値は等値として扱います。「厳密」な比較を行いたい場合は、containsStrictメソッドを使ってください。The contains method uses "loose" comparisons when checking item values, meaning a string with an integer value will be considered equal to an integer of the same value. Use the containsStrict[#method-containsstrict] method to filter using "strict" comparisons.

For the inverse of contains, see the doesntContain method.For the inverse of contains, see the doesntContain[#method-doesntcontain] method.

containsStrict() containsStrict()

このメソッドは、containsメソッドと使用方法は同じです。しかし、「厳密」な値の比較を行います。This method has the same signature as the contains[#method-contains] method; however, all values are compared using "strict" comparisons.

lightbulb">Tip!! Eloquentコレクションの使用時は、このメソッドの振る舞いは変わります。{tip} This method's behavior is modified when using Eloquent Collections[/docs/{{version}}/eloquent-collections#method-contains].

count() count()

countメソッドはコレクションのアイテム数を返します。The count method returns the total number of items in the collection:

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

$collection->count();

// 4

countBy() countBy()

countByメソッドは、コレクション内の値の出現をカウントします。このメソッドはデフォルトで、コレクション内の要素の特定の「タイプ」をカウントできるよう、すべての要素の出現をカウントします。The countBy method counts the occurrences of values in the collection. By default, the method counts the occurrences of every element, allowing you to count certain "types" of elements in the collection:

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

$counted = $collection->countBy();

$counted->all();

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

countByメソッドにクロージャを渡して、すべてのアイテムをカスタム値でカウントします。You pass a closure to the countBy method to count all items by a custom value:

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

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

$counted->all();

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

crossJoin() crossJoin()

crossJoinメソッドはコレクションの値と、指定した配列かコレクション間の値を交差接続し、可能性のある全順列の直積を返します。The crossJoin method cross joins the collection's values among the given arrays or collections, returning a Cartesian product with all possible permutations:

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

ddメソッドはコレクションアイテムをダンプし、スクリプトの実行を停止します。The dd method dumps the collection's items and ends execution of the script:

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

$collection->dd();

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

スクリプトの実行を止めたくない場合は、dumpメソッドを代わりに使用してください。If you do not want to stop executing the script, use the dump[#method-dump] method instead.

diff() diff()

diffメソッドはコレクションと、他のコレクションか一次元「配列」を値にもとづき比較します。このメソッドは指定されたコレクションに存在しない、オリジナルのコレクションの値を返します。The diff method compares the collection against another collection or a plain PHP array based on its values. This method will return the values in the original collection that are not present in the given collection:

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

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

$diff->all();

// [1, 3, 5]

lightbulb">Tip!! Eloquentコレクションの使用時は、このメソッドの振る舞いは変わります。{tip} This method's behavior is modified when using Eloquent Collections[/docs/{{version}}/eloquent-collections#method-diff].

diffAssoc() diffAssoc()

diffAssocメソッドはコレクションと、他のコレクションかキー／値形式のPHP配列を比較します。このメソッドは指定したコレクションに含まれない、オリジナルコレクション中のキー／値ペアを返します。The diffAssoc method compares the collection against another collection or a plain PHP array based on its keys and values. This method will return the key / value pairs in the original collection that are not present in the given 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]

diffKeys() diffKeys()

diffKeysメソッドはコレクションと、他のコレクションか一次元「配列」をキーで比較します。このメソッドは指定したコレクションに存在しない、オリジナルコレクション中のキー／値ペアを返します。The diffKeys method compares the collection against another collection or a plain PHP array based on its keys. This method will return the key / value pairs in the original collection that are not present in the given collection:

$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 メソッドは、コレクションに指定アイテムが含まれないことを判定します。doesntContain メソッドにクロージャを渡し、指定する真理値テストに合致する要素がコレクションに存在ことを判定できます。The doesntContain method determines whether the collection does not contain a given item. You may pass a closure to the doesntContain method to determine if an element does not exist in the collection matching a given truth test:

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

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

// false

あるいは、doesntContainメソッドに文字列を渡し、コレクションに指定したアイテム値が含まれていないことを判定することもできます。Alternatively, you may pass a string to the doesntContain method to determine whether the collection does not contain a given item value:

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

$collection->doesntContain('Table');

// true

$collection->doesntContain('Desk');

// false

また、doesntContainメソッドへキー／値のペアを渡し、指定ペアがコレクション内に存在しないことを判定することも可能です。You may also pass a key / value pair to the doesntContain method, which will determine if the given pair does not exist in the collection:

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

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

// true

doesntContainメソッドは、項目の値をチェックする際、「緩く」比較します。つまり、整数値を持つ文字列は同じ値の整数値と等しいとみなします。The doesntContain method uses "loose" comparisons when checking item values, meaning a string with an integer value will be considered equal to an integer of the same value.

dump() dump()

dumpメソッドはコレクションアイテムをダンプします。The dump method dumps the collection's items:

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

$collection->dump();

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

コレクションをダンプした後にスクリプトを停止したい場合は、代わりにddメソッドを使用してください。If you want to stop executing the script after dumping the collection, use the dd[#method-dd] method instead.

duplicates() duplicates()

duplicatesメソッドはコレクション中の重複値を返します。The duplicates method retrieves and returns duplicate values from the collection:

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

$collection->duplicates();

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

コレクションが配列やオブジェクトを含む場合は、値の重複を調べたい属性のキーを渡せます。If the collection contains arrays or objects, you can pass the key of the attributes that you wish to check for duplicate values:

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

このメソッドの使い方はduplicatesメソッドと同じですが、すべての値に「厳密な」比較が行われます。This method has the same signature as the duplicates[#method-duplicates] method; however, all values are compared using "strict" comparisons.

each() each()

eachメソッドはコレクション内のアイテムを反復処理し、各アイテムをクロージャに渡します。The each method iterates over the items in the collection and passes each item to a closure:

$collection->each(function ($item, $key) {
    //
});

アイテムの反復を停止したい場合は、クロージャからfalseを返してください。If you would like to stop iterating through the items, you may return false from your closure:

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

eachSpread() eachSpread()

eachSpreadメソッドはコレクションのアイテムに対し、指定したコールバックへネストしたアイテム値をそれぞれ渡し、繰り返し処理します。The eachSpread method iterates over the collection's items, passing each nested item value into the given callback:

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

$collection->eachSpread(function ($name, $age) {
    //
});

アイテムに対する繰り返しを停止したい場合は、コールバックからfalseを返します。You may stop iterating through the items by returning false from the callback:

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

every() every()

everyメソッドは、コレクションの全要素が、指定したテストをパスするか判定するために使用します。The every method may be used to verify that all elements of a collection pass a given truth test:

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

// false

コレクションが空の場合、everyメソッドはtrueを返します。If the collection is empty, the every method will return true:

$collection = collect([]);

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

// true

except() except()

exceptメソッドは、キーにより指定したアイテム以外の全コレクション要素を返します。The except method returns all items in the collection except for those with the specified keys:

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

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

$filtered->all();

// ['product_id' => 1]

exceptの正反対の機能は、onlyメソッドです。For the inverse of except, see the only[#method-only] method.

lightbulb">Tip!! Eloquentコレクションの使用時は、このメソッドの振る舞いは変わります。{tip} This method's behavior is modified when using Eloquent Collections[/docs/{{version}}/eloquent-collections#method-except].

filter() filter()

filterメソッドは指定したコールバックでコレクションをフィルタリングします。テストでtrueを返したアイテムだけが残ります。The filter method filters the collection using the given callback, keeping only those items that pass a given truth test:

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

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

$filtered->all();

// [3, 4]

コールバックを指定しない場合、コレクションの全エンティティの中で、falseとして評価されるものを削除します。If no callback is supplied, all entries of the collection that are equivalent to false will be removed:

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

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

// [1, 2, 3]

filterの逆の動作は、rejectメソッドを見てください。For the inverse of filter, see the reject[#method-reject] method.

first() first()

firstメソッドは指定された真偽テストをパスしたコレクションの最初の要素を返します。The first method returns the first element in the collection that passes a given truth test:

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

// 3

firstメソッドに引数を付けなければ、コレクションの最初の要素を取得できます。コレクションが空ならnullを返します。You may also call the first method with no arguments to get the first element in the collection. If the collection is empty, null is returned:

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

// 1

firstWhere() firstWhere()

firstWhereメソッドはコレクションの中から、最初の指定したキー／値ペアの要素を返します。The firstWhere method returns the first element in the collection with the given key / value pair:

$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メソッドを呼び出すこともできます。You may also call the firstWhere method with a comparison operator:

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

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

whereメソッドと同様に、firstWhereメソッドへ一つの引数を渡せます。その場合、firstWhereメソッドは、指定したアイテムキー値が「真と見なせる」最初のアイテムを返します。Like the where[#method-where] method, you may pass one argument to the firstWhere method. In this scenario, the firstWhere method will return the first item where the given item key's value is "truthy":

$collection->firstWhere('age');

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

flatMap() flatMap()

flatMapメソッドはコレクションを反復処理し、各値を指定したクロージャに渡します。クロージャはアイテムを自由に変更して返却できるため、変更されたアイテムの新しいコレクションを形成します。それから、一次配列へフラット化します。The flatMap method iterates through the collection and passes each value to the given closure. The closure is free to modify the item and return it, thus forming a new collection of modified items. Then, the array is flattened by one level:

$collection = collect([
    ['name' => 'Sally'],
    ['school' => 'Arkansas'],
    ['age' => 28]
]);

$flattened = $collection->flatMap(function ($values) {
    return array_map('strtoupper', $values);
});

$flattened->all();

// ['name' => 'SALLY', 'school' => 'ARKANSAS', 'age' => '28'];

flatten() flatten()

flattenメソッドは多次元コレクションを一次元化します。The flatten method flattens a multi-dimensional collection into a single dimension:

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

$flattened = $collection->flatten();

$flattened->all();

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

必要に応じて、flattenメソッドに「depth」引数を渡すことができます。If necessary, you may pass the flatten method a "depth" argument:

$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を呼び出すと、ネストした配列もフラットにし、['iPhone6S'、'Apple'、'GalaxyS7'、'Samsung']になります。深さを指定すると、ネストした配列をフラット化するレベルの数を指定できます。In this example, calling flatten without providing the depth would have also flattened the nested arrays, resulting in ['iPhone 6S', 'Apple', 'Galaxy S7', 'Samsung']. Providing a depth allows you to specify the number of levels nested arrays will be flattened.

flip() flip()

flipメソッドはコレクションのキーと対応する値を入れ替えます。The flip method swaps the collection's keys with their corresponding values:

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

$flipped = $collection->flip();

$flipped->all();

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

forget() forget()

forgetメソッドはキーによりコレクションのアイテムを削除します。The forget method removes an item from the collection by its key:

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

$collection->forget('name');

$collection->all();

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

Note: note 他のコレクションメソッドとは異なり、forgetは更新された新しいコレクションを返しません。呼び出しもとのコレクションを更新します。{note} Unlike most other collection methods, forget does not return a new modified collection; it modifies the collection it is called on.

forPage() forPage()

forPageメソッドは指定されたページ番号を表すアイテムで構成された新しいコレクションを返します。このメソッドは最初の引数にページ番号、２つ目の引数としてページあたりのアイテム数を受け取ります。The forPage method returns a new collection containing the items that would be present on a given page number. The method accepts the page number as its first argument and the number of items to show per page as its second argument:

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

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

$chunk->all();

// [4, 5, 6]

get() get()

getメソッドは指定されたキーのアイテムを返します。キーが存在していない場合はnullを返します。The get method returns the item at a given key. If the key does not exist, null is returned:

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

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

// taylor

オプションとして第２引数にデフォルト値を指定することもできます。You may optionally pass a default value as the second argument:

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

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

// 34

メソッドのデフォルト値としてコールバックを渡すこともできます。指定したキーが存在しない場合、コールバックの結果が返されます。You may even pass a callback as the method's default value. The result of the callback will be returned if the specified key does not exist:

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

// taylor@example.com

groupBy() groupBy()

groupByメソッドは指定したキーによりコレクションのアイテムをグループにまとめます。The groupBy method groups the collection's items by a given key:

$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を指定する代わりに、コールバックを渡すことができます。コールバックはグループとしてまとめるキーの値を返す必要があります。Instead of passing a string key, you may pass a callback. The callback should return the value you wish to key the group by:

$grouped = $collection->groupBy(function ($item, $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'],
        ],
    ]
*/

配列として、複数のグルーピング基準を指定できます。各配列要素は多次元配列の対応するレベルへ適用されます。Multiple grouping criteria may be passed as an array. Each array element will be applied to the corresponding level within a multi-dimensional 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 ($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()

hasメソッドは指定したキーがコレクションに存在しているかを調べます。The has method determines if a given key exists in the collection:

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

$collection->has('product');

// true

$collection->has(['product', 'amount']);

// true

$collection->has(['amount', 'price']);

// false

implode() implode()

implodeメソッドはコレクション内のアイテムを結合します。その引数は、コレクション内のアイテムのタイプによって異なります。コレクションに配列またはオブジェクトが含まれている場合は、結合する属性のキーと、値の間に配置する「接着」文字列を渡す必要があります。The implode method joins items in a collection. Its arguments depend on the type of items in the collection. If the collection contains arrays or objects, you should pass the key of the attributes you wish to join, and the "glue" string you wish to place between the values:

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

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

// Desk, Chair

コレクションに単純な文字列または数値が含まれている場合は、メソッドへの唯一の引数として「接着」文字列を渡す必要があります。If the collection contains simple strings or numeric values, you should pass the "glue" as the only argument to the method:

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

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

intersect() intersect()

intersectメソッドは、指定した「配列」かコレクションに存在していない値をオリジナルコレクションから取り除きます。結果のコレクションには、オリジナルコレクションのキーがリストされます。The intersect method removes any values from the original collection that are not present in the given array or collection. The resulting collection will preserve the original collection's keys:

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

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

$intersect->all();

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

lightbulb">Tip!! Eloquentコレクションの使用時は、このメソッドの振る舞いは変わります。{tip} This method's behavior is modified when using Eloquent Collections[/docs/{{version}}/eloquent-collections#method-intersect].

intersectByKeys() intersectByKeys()

intersectByKeysメソッドは、指定した配列またはコレクションに存在しないキーとそれに対応する値を元のコレクションから削除します。The intersectByKeys method removes any keys and their corresponding values from the original collection that are not present in the given array or collection:

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

isEmptyメソッドはコレクションが空の場合にtrueを返します。そうでなければfalseを返します。The isEmpty method returns true if the collection is empty; otherwise, false is returned:

collect([])->isEmpty();

// true

isNotEmpty() isNotEmpty()

isNotEmptyメソッドは、コレクションが空でない場合にtrueを返します。空であればfalseを返します。The isNotEmpty method returns true if the collection is not empty; otherwise, false is returned:

collect([])->isNotEmpty();

// false

join() join()

joinメソッドは、コレクションの値を文字列で結合します。このメソッドの２番目の引数を使用して、最後の要素を文字列に追加する方法を指定することもできます。The join method joins the collection's values with a string. Using this method's second argument, you may also specify how the final element should be appended to the 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() keyBy()

keyByメソッドは指定したキーをコレクションのキーにします。複数のアイテムが同じキーを持っている場合、新しいコレクションには最後のアイテムが含まれます。The keyBy method keys the collection by the given key. If multiple items have the same key, only the last one will appear in the new 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'],
    ]
*/

もしくは、コールバックをメソッドへ渡すこともできます。コールバックからコレクションのキーの値を返してください。You may also pass a callback to the method. The callback should return the value to key the collection by:

$keyed = $collection->keyBy(function ($item) {
    return strtoupper($item['product_id']);
});

$keyed->all();

/*
    [
        'PROD-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
        'PROD-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
    ]
*/

keys() keys()

keysメソッドはコレクションの全キーを返します。The keys method returns all of the collection's 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()

lastメソッドは指定したテストをパスしたコレクションの最後のアイテムを返します。The last method returns the last element in the collection that passes a given truth test:

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

// 2

またはlastメソッドを引数無しで呼び出し、コレクションの最後の要素を取得することもできます。コレクションが空の場合、nullが返ります。You may also call the last method with no arguments to get the last element in the collection. If the collection is empty, null is returned:

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

// 4

macro() macro()

staticのmacroメソッドで、実行時にCollectionクラスへメソッドを追加できます。詳細は、コレクションの拡張ドキュメントを参照してください。The static macro method allows you to add methods to the Collection class at run time. Refer to the documentation on extending collections[#extending-collections] for more information.

make() make()

staticのmakeメソッドは、新しいコレクションインスタンスを生成します。コレクションの生成セクションを参照してください。The static make method creates a new collection instance. See the Creating Collections[#creating-collections] section.

map() map()

mapメソッドコレクション全体を繰り返しで処理し、指定したコールバックから値を返します。コールバックで自由にアイテムを更新し値を返せます。更新したアイテムの新しいコレクションが作成されます。The map method iterates through the collection and passes each value to the given callback. The callback is free to modify the item and return it, thus forming a new collection of modified items:

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

$multiplied = $collection->map(function ($item, $key) {
    return $item * 2;
});

$multiplied->all();

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

Note: note 他のコレクションと同様にmapは新しいコレクションインスタンスを返します。呼び出し元のコレクションは変更しません。もしオリジナルコレクションを変更したい場合はtransformメソッドを使います。{note} Like most other collection methods, map returns a new collection instance; it does not modify the collection it is called on. If you want to transform the original collection, use the transform[#method-transform] method.

mapInto() mapInto()

mapInto()メソッドはコレクションを繰り返し処理します。指定したクラスの新しいインスタンスを生成し、コンストラクタへ値を渡します。The mapInto() method iterates over the collection, creating a new instance of the given class by passing the value into the constructor:

class Currency
{
    /**
     * 新しい通貨インスタンスの生成
     *
     * @param  string  $code
     * @return void
     */
    function __construct(string $code)
    {
        $this->code = $code;
    }
}

$collection = collect(['USD', 'EUR', 'GBP']);

$currencies = $collection->mapInto(Currency::class);

$currencies->all();

// [Currency('USD'), Currency('EUR'), Currency('GBP')]

mapSpread() mapSpread()

mapSpreadメソッドはコレクションのアイテムを反復処理し、ネストした各アイテム値を指定されたクロージャに渡します。クロージャはアイテムを自由に変更して返すことができるため、変更したアイテムの新しいコレクションを生成します。The mapSpread method iterates over the collection's items, passing each nested item value into the given closure. The closure is free to modify the item and return it, thus forming a new collection of modified items:

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

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

$sequence = $chunks->mapSpread(function ($even, $odd) {
    return $even + $odd;
});

$sequence->all();

// [1, 5, 9, 13, 17]

mapToGroups() mapToGroups()

mapToGroupsメソッドは、指定クロージャによってコレクションのアイテムをグループ化します。クロージャはキー／値のペアを一つ含む連想配列を返してください。これにより、値をグループ化した新しいコレクションを生成します。The mapToGroups method groups the collection's items by the given closure. The closure should return an associative array containing a single key / value pair, thus forming a new collection of grouped values:

$collection = collect([
    [
        'name' => 'John Doe',
        'department' => 'Sales',
    ],
    [
        'name' => 'Jane Doe',
        'department' => 'Sales',
    ],
    [
        'name' => 'Johnny Doe',
        'department' => 'Marketing',
    ]
]);

$grouped = $collection->mapToGroups(function ($item, $key) {
    return [$item['department'] => $item['name']];
});

$grouped->all();

/*
    [
        'Sales' => ['John Doe', 'Jane Doe'],
        'Marketing' => ['Johnny Doe'],
    ]
*/

$grouped->get('Sales')->all();

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

mapWithKeys() mapWithKeys()

mapWithKeysメソッドはコレクション全体を反復処理し、指定したコールバックへ各値を渡します。コールバックからキー／値ペアを一つ含む連想配列を返してください。The mapWithKeys method iterates through the collection and passes each value to the given callback. The callback should return an associative array containing a single key / value pair:

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

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

$keyed->all();

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

max() max()

maxメソッドは、指定したキーの最大値を返します。The max method returns the maximum value of a given key:

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

// 20

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

// 5

median() median()

medianメソッドは、指定したキーの中央値を返します。The median method returns the median value[https://en.wikipedia.org/wiki/Median] of a given key:

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

// 15

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

// 1.5

merge() merge()

mergeメソッドは、指定した配列かコレクションをオリジナルコレクションへマージします。指定した配列の文字列キーが、オリジナルコレクションの文字列キーと一致する場合、オリジナルコレクションの値は指定アイテムの値でオーバーライトされます。The merge method merges the given array or collection with the original collection. If a string key in the given items matches a string key in the original collection, the given items's value will overwrite the value in the original collection:

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

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

$merged->all();

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

指定したアイテムのキーが数値の場合、コレクションの最後に追加されます。If the given items's keys are numeric, the values will be appended to the end of the collection:

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

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

$merged->all();

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

mergeRecursive() mergeRecursive()

mergeRecursiveメソッドはオリジナルのコレクションに対し、指定した配列かコレクションを再帰的にマージします。指定したアイテムの文字列キーがオリジナルコレクションのものと一致したら、それらのキーに対する値を配列へマージします。これを再帰的に行います。The mergeRecursive method merges the given array or collection recursively with the original collection. If a string key in the given items matches a string key in the original collection, then the values for these keys are merged together into an array, and this is done recursively:

$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メソッドは、指定したキーの最小値を返します。The min method returns the minimum value of a given key:

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

// 10

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

// 1

mode() mode()

modeメソッドは、指定したキーの最頻値を返します。The mode method returns the mode value[https://en.wikipedia.org/wiki/Mode_(statistics)] of a given key:

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

nthメソッドは指定数値間隔で要素を含む、新しいコレクションを生成します。The nth method creates a new collection consisting of every n-th element:

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

$collection->nth(4);

// ['a', 'e']

オプションで、２番目の引数として開始オフセットを指定できます。You may optionally pass a starting offset as the second argument:

$collection->nth(4, 1);

// ['b', 'f']

only() only()

onlyメソッドは、コレクション中の指定したアイテムのみを返します。The only method returns the items in the collection with the specified keys:

$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メソッドです。For the inverse of only, see the except[#method-except] method.

lightbulb">Tip!! Eloquentコレクションの使用時は、このメソッドの振る舞いは変わります。{tip} This method's behavior is modified when using Eloquent Collections[/docs/{{version}}/eloquent-collections#method-only].

pad() pad()

padメソッドは、配列が指定したサイズに達するまで、指定値で配列を埋めます。このメソッドはarray_pad PHP関数のような動作をします。The pad method will fill the array with the given value until the array reaches the specified size. This method behaves like the array_pad[https://secure.php.net/manual/en/function.array-pad.php] PHP function.

先頭を埋めるためには、サイズに負数を指定します。配列サイズ以下のサイズ値を指定した場合は、埋め込みを行いません。To pad to the left, you should specify a negative size. No padding will take place if the absolute value of the given size is less than or equal to the length of the array:

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

partitionメソッドは、PHPの配列のデストラクションと組み合わせて、与えられた真理値テストに合格した要素とそうでない要素を分離できます。The partition method may be combined with PHP array destructuring to separate elements that pass a given truth test from those that do not:

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

[$underThree, $equalOrAboveThree] = $collection->partition(function ($i) {
    return $i < 3;
});

$underThree->all();

// [1, 2]

$equalOrAboveThree->all();

// [3, 4, 5, 6]

pipe() pipe()

pipeメソッドは、コレクションを指定したクロージャに渡し、実行されたクロージャの結果を返します。The pipe method passes the collection to the given closure and returns the result of the executed closure:

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

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

// 6

pipeInto() pipeInto()

pipeIntoメソッドは、指定クラスの新しいインスタンスを生成し、コレクションをコンストラクターに渡します。The pipeInto method creates a new instance of the given class and passes the collection into the constructor:

class ResourceCollection
{
    /**
     * コレクションインスタンス
     */
    public $collection;

    /**
     * 新しいResourceCollectionインスタンスの生成
     *
     * @param  Collection  $collection
     * @return void
     */
    public function __construct(Collection $collection)
    {
        $this->collection = $collection;
    }
}

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

$resource = $collection->pipeInto(ResourceCollection::class);

$resource->collection->all();

// [1, 2, 3]

pipeThrough() pipeThrough()

pipeThroughメソッドは、指定するクロージャの配列へコレクションを渡し、クロージャの実行結果を返します。The pipeThrough method passes the collection to the given array of closures and returns the result of the executed closures:

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

$result = $collection->pipeThrough([
    function ($collection) {
        return $collection->merge([4, 5]);
    },
    function ($collection) {
        return $collection->sum();
    },
]);

// 15

pluck() pluck()

pluckメソッドは指定したキーの全コレクション値を取得します。The pluck method retrieves all of the values for a given key:

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

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

$plucked->all();

// ['Desk', 'Chair']

さらに、コレクションのキー項目も指定できます。You may also specify how you wish the resulting collection to be keyed:

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

$plucked->all();

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

pluckメソッドは、「ドット」記法を使ったネストしている値の取得もサポートしています。The pluck method also supports retrieving nested values using "dot" notation:

$collection = collect([
    [
        'speakers' => [
            'first_day' => ['Rosa', 'Judith'],
            'second_day' => ['Angela', 'Kathleen'],
        ],
    ],
]);

$plucked = $collection->pluck('speakers.first_day');

$plucked->all();

// ['Rosa', 'Judith']

重複するキーが存在している場合は、最後に一致した要素が結果のコレクションへ挿入されます。If duplicate keys exist, the last matching element will be inserted into the plucked 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()

popメソッドはコレクションの最後のアイテムを削除し、返します。The pop method removes and returns the last item from the collection:

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

$collection->pop();

// 5

$collection->all();

// [1, 2, 3, 4]

コレクションの最後から複数の項目を削除して返すために、整数をpopメソッドに渡せます。You may pass an integer to the pop method to remove and return multiple items from the end of a collection:

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

$collection->pop(3);

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

$collection->all();

// [1, 2]

prepend() prepend()

prependメソッドはアイテムをコレクションの最初に追加します。The prepend method adds an item to the beginning of the collection:

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

$collection->prepend(0);

$collection->all();

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

２番目の引数で、先頭に追加するアイテムのキーを指定することもできます。You may also pass a second argument to specify the key of the prepended item:

$collection = collect(['one' => 1, 'two' => 2]);

$collection->prepend(0, 'zero');

$collection->all();

// ['zero' => 0, 'one' => 1, 'two' => 2]

pull() pull()

pullメソッドはキーによりアイテムを削除し、そのアイテムを返します。The pull method removes and returns an item from the collection by its key:

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

$collection->pull('name');

// 'Desk'

$collection->all();

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

push() push()

pushメソッドはコレクションの最後にアイテムを追加します。The push method appends an item to the end of the collection:

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

$collection->push(5);

$collection->all();

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

put() put()

putメソッドは指定したキーと値をコレクションにセットします。The put method sets the given key and value in the collection:

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

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

$collection->all();

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

random() random()

randomメソッドはコレクションからランダムにアイテムを返します。The random method returns a random item from the collection:

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

$collection->random();

// 4 - (ランダムに取得)

整数をrandomに渡して、ランダムに取得するアイテムの数を指定できます。受け取りたいアイテムの数を明示的に渡すと、アイテムのコレクションが常に返されます。You may pass an integer to random to specify how many items you would like to randomly retrieve. A collection of items is always returned when explicitly passing the number of items you wish to receive:

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

$random->all();

// [2, 4, 5] - (ランダムに取得)

コレクションインスタンスのアイテム数が要求より少ない場合、randomメソッドはInvalidArgumentExceptionを投げます。If the collection instance has fewer items than requested, the random method will throw an InvalidArgumentException.

range() range()

rangeメソッドは、指定範囲の整数を含むコレクションを返します。The range method returns a collection containing integers between the specified range:

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

$collection->all();

// [3, 4, 5, 6]

reduce() reduce()

reduceメソッドは繰り返しの結果を次の繰り返しに渡しながら、コレクションを単一値へ減らします。The reduce method reduces the collection to a single value, passing the result of each iteration into the subsequent iteration:

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

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

// 6

最初の繰り返しの$carryの値はnullです。しかし初期値を設定したい場合は、reduceの第２引数に渡してください。The value for $carry on the first iteration is null; however, you may specify its initial value by passing a second argument to reduce:

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

// 10

また、reduceメソッドは、配列のキーを連想コレクションにして、与えられたコールバックに渡します。The reduce method also passes array keys in associative collections to the given callback:

$collection = collect([
    'usd' => 1400,
    'gbp' => 1200,
    'eur' => 1000,
]);

$ratio = [
    'usd' => 1,
    'gbp' => 1.37,
    'eur' => 1.22,
];

$collection->reduce(function ($carry, $value, $key) use ($ratio) {
    return $carry + ($value * $ratio[$key]);
});

// 4264

reduceSpread() reduceSpread()

reduceSpreadメソッドはコレクションを値の配列に減らし、各反復の結果を後続の反復に渡します。このメソッドはreduceメソッドと似ていますが、複数の初期値を受け入れることができます。The reduceSpread method reduces the collection to an array of values, passing the results of each iteration into the subsequent iteration. This method is similar to the reduce method; however, it can accept multiple initial values:

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

                $creditsRemaining -= $image->creditsRequired();
            }

            return [$creditsRemaining, $batch];
        }, $creditsAvailable, collect());

reject() reject()

rejectメソッドは、指定したクロージャを使用してコレクションをフィルタリングします。結果のコレクションからアイテムを削除する必要がある場合、クロージャでtrueを返してください。The reject method filters the collection using the given closure. The closure should return true if the item should be removed from the resulting collection:

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

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

$filtered->all();

// [1, 2]

rejectメソッドの逆の働きについては、filterメソッドを読んでください。For the inverse of the reject method, see the filter[#method-filter] method.

replace() replace()

replaceメソッドは、mergeメソッドと似た振る舞いを行います。文字列キーを持っているアイテムをオーバーライドするのは同じですが、replaceメソッドは数値キーに一致するコレクション中のアイテムもオーバーライドします。The replace method behaves similarly to merge; however, in addition to overwriting matching items that have string keys, the replace method will also overwrite items in the collection that have matching numeric keys:

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

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

$replaced->all();

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

replaceRecursive() replaceRecursive()

このメソッドはreplaceと似た動作をしますが、配列を再帰的に下り、次元の低い値も同様に置換します。This method works like replace, but it will recur into arrays and apply the same replacement process to the inner values:

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

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

$replaced->all();

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

reverse() reverse()

reverseメソッドはオリジナルのキーを保ったまま、コレクションのアイテムの順番を逆にします。The reverse method reverses the order of the collection's items, preserving the original keys:

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

$reversed = $collection->reverse();

$reversed->all();

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

search() search()

searchメソッドは、コレクションを検索し、指定値が見つかった場合はそのキーを返します。アイテムが見つからない場合、falseを返します。The search method searches the collection for the given value and returns its key if found. If the item is not found, false is returned:

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

$collection->search(4);

// 1

検索は「緩い」比較で行われます。つまり、整数値を持つ文字列は、同じ値の整数に等しいと判断されます。「厳格」な比較を行いたい場合はtrueをメソッドの第２引数に渡します。The search is done using a "loose" comparison, meaning a string with an integer value will be considered equal to an integer of the same value. To use "strict" comparison, pass true as the second argument to the method:

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

// false

または、独自のクロージャを提供して、指定するテストに合格した最初のアイテムを検索することもできます。Alternatively, you may provide your own closure to search for the first item that passes a given truth test:

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

// 2

shift() shift()

shiftメソッドはコレクションから最初のアイテムを削除し、その値を返します。The shift method removes and returns the first item from the collection:

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

$collection->shift();

// 1

$collection->all();

// [2, 3, 4, 5]

コレクションの先頭から複数の項目を削除して返すために、整数をshiftメソッドに渡せます。You may pass an integer to the shift method to remove and return multiple items from the beginning of a collection:

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

$collection->shift(3);

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

$collection->all();

// [4, 5]

shuffle() shuffle()

shuffleメソッドはコレクションのアイテムをランダムにシャッフルします。The shuffle method randomly shuffles the items in the collection:

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

$shuffled = $collection->shuffle();

$shuffled->all();

// [3, 2, 5, 1, 4] - (ランダムに生成される)

sliding() sliding()

slidingメソッドは、コレクション中のアイテムの「スライディングウィンドウ」ビューを表す新しいチャンクコレクションを返します。The sliding method returns a new collection of chunks representing a "sliding window" view of the items in the collection:

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

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

$chunks->toArray();

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

これはeachSpreadメソッドと組み合わせて使うと、特に便利です。This is especially useful in conjunction with the eachSpread[#method-eachspread] method:

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

必要に応じて、それぞれのチャンクの最初の項目間にどのくらい距離を取るかを決定する２番目の「ステップ」値を渡せます。You may optionally pass a second "step" value, which determines the distance between the first item of every chunk:

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

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

$chunks->toArray();

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

skip() skip()

skipメソッドは、コレクションの先頭から指定した数の要素を削除した新しいコレクションを返します。The skip method returns a new collection, with the given number of elements removed from the beginning of the 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()

skipUntilメソッドは、指定したコールバックがtrueを返すまでコレクションからアイテムをスキップし、コレクション内の残りのアイテムを新しいコレクションインスタンスとして返します。The skipUntil method skips over items from the collection until the given callback returns true and then returns the remaining items in the collection as a new collection instance:

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

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

$subset->all();

// [3, 4]

もしくはシンプルに値をskipUntilメソッドへ渡すこともでき、その場合は指定した値が見つかるまでアイテムをスキップします。You may also pass a simple value to the skipUntil method to skip all items until the given value is found:

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

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

$subset->all();

// [3, 4]

Note: note 指定した値が見つからないか、コールバックがtrueを返さなかった場合、skipUntilメソッドは空のコレクションを返します。{note} If the given value is not found or the callback never returns true, the skipUntil method will return an empty collection.

skipWhile() skipWhile()

skipWhileメソッドは、指定したコールバックがtrueを返す間、コレクションからアイテムをスキップし、コレクション内の残りのアイテムを新しいコレクションとして返します。The skipWhile method skips over items from the collection while the given callback returns true and then returns the remaining items in the collection as a new collection:

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

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

$subset->all();

// [4]

Note: note コールバックがfalseを返さなかった場合、skipWhileメソッドは空のコレクションを返します。{note} If the callback never returns false, the skipWhile method will return an empty collection.

slice() slice()

sliceメソッドは指定したインデックスからコレクションを切り分けます。The slice method returns a slice of the collection starting at the given index:

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

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

$slice->all();

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

切り分ける数を制限したい場合は、メソッドの第２引数で指定してください。If you would like to limit the size of the returned slice, pass the desired size as the second argument to the method:

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

$slice->all();

// [5, 6]

sliceメソッドはデフォルトでキー値を保持したまま返します。オリジナルのキーを保持したくない場合は、valuesメソッドを使えば、インデックスし直されます。The returned slice will preserve keys by default. If you do not wish to preserve the original keys, you can use the values[#method-values] method to reindex them.

sole() sole()

soleメソッドは、指定した真偽テストをパスしたアイテムが正確に１つだけの場合、コレクション内の最初の要素を返します。The sole method returns the first element in the collection that passes a given truth test, but only if the truth test matches exactly one element:

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

// 2

キー／値のペアをsoleメソッドへ渡すこともできます。この場合、指定したペアに一致するコレクション内のアイテムが正確に１つだけの場合、それを返します。You may also pass a key / value pair to the sole method, which will return the first element in the collection that matches the given pair, but only if it exactly one element matches:

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

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

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

もしくは、要素が１つしかない場合は、引数を指定せずにsoleメソッドを呼び出すこともできます。Alternatively, you may also call the sole method with no argument to get the first element in the collection if there is only one element:

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

$collection->sole();

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

コレクション内に、soleメソッドが返すべき要素がない場合、\Illuminate\Collections\ItemNotFoundException例外を投げます。返すべき要素が複数ある場合は、\Illuminate\Collections\MultipleItemsFoundExceptionを投げます。If there are no elements in the collection that should be returned by the sole method, an \Illuminate\Collections\ItemNotFoundException exception will be thrown. If there is more than one element that should be returned, an \Illuminate\Collections\MultipleItemsFoundException will be thrown.

some() some()

containsメソッドのエイリアスです。Alias for the contains[#method-contains] method.

sort() sort()

sortメソッドはコレクションをソートします。ソート済みコレクションはオリジナル配列のキーを保持しますので、以下の例では、valuesメソッドにより、連続した数字のインデックスにするためリセットしています。The sort method sorts the collection. The sorted collection keeps the original array keys, so in the following example we will use the values[#method-values] method to reset the keys to consecutively numbered indexes:

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

$sorted = $collection->sort();

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

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

より高度なソートを行いたい場合はsortにコールバックを渡し、自分のアルゴリズムを実行できます。コレクションのsortメソッドが使用しているuasortのPHPドキュメントを参照してください。If your sorting needs are more advanced, you may pass a callback to sort with your own algorithm. Refer to the PHP documentation on uasort[https://secure.php.net/manual/en/function.uasort.php#refsect1-function.uasort-parameters], which is what the collection's sort method calls utilizes internally.

lightbulb">Tip!! ネストした配列やオブジェクトのコレクションのソートは、sortByとsortByDescメソッドを参照してください。{tip} If you need to sort a collection of nested arrays or objects, see the sortBy[#method-sortby] and sortByDesc[#method-sortbydesc] methods.

sortBy() sortBy()

sortByメソッドは指定したキーでコレクションをソートします。ソート済みコレクションはオリジナル配列のキーを保持しますので、以下の例では、valuesメソッドにより、連続した数字のインデックスにするためリセットしています。The sortBy method sorts the collection by the given key. The sorted collection keeps the original array keys, so in the following example we will use the values[#method-values] method to reset the keys to consecutively numbered indexes:

$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メソッドは第２引数に、ソートフラグを受け取ります。The sortBy method accepts sort flags[https://www.php.net/manual/en/function.sort.php] as its second argument:

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

または、独自のクロージャを渡して、コレクションの値を並べ替える方法を決定することもできます。Alternatively, you may pass your own closure to determine how to sort the collection's values:

$collection = collect([
    ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
    ['name' => 'Chair', 'colors' => ['Black']],
    ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
]);

$sorted = $collection->sortBy(function ($product, $key) {
    return count($product['colors']);
});

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

/*
    [
        ['name' => 'Chair', 'colors' => ['Black']],
        ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
        ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
    ]
*/

コレクションを複数の属性で並べ替える場合は、並べ替え操作の配列を sortByメソッドに渡すことができます。各並べ替え操作は、並べ替える属性と目的の並べ替えの方向で構成される配列です。If you would like to sort your collection by multiple attributes, you may pass an array of sort operations to the sortBy method. Each sort operation should be an array consisting of the attribute that you wish to sort by and the direction of the desired sort:

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

コレクションを複数の属性で並べ替える場合、各並べ替え操作を定義するクロージャを指定することもできます。When sorting a collection by multiple attributes, you may also provide closures that define each sort operation:

$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 ($a, $b) => $a['name'] <=> $b['name'],
    fn ($a, $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() sortByDesc()

このメソッドの使い方はsortByと同じで、コレクションを逆順にソートします。This method has the same signature as the sortBy[#method-sortby] method, but will sort the collection in the opposite order.

sortDesc() sortDesc()

このメソッドはsortメソッドの逆順でコレクションをソートします。This method will sort the collection in the opposite order as the sort[#method-sort] method:

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

$sorted = $collection->sortDesc();

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

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

sortとは異なり、sortDescにクロージャを渡すことはできません。代わりに、sortメソッドを使用して、比較を逆にする必要があります。Unlike sort, you may not pass a closure to sortDesc. Instead, you should use the sort[#method-sort] method and invert your comparison.

sortKeys() sortKeys()

sortKeysメソッドは、内部の連想配列のキーにより、コレクションをソートします。The sortKeys method sorts the collection by the keys of the underlying associative array:

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

$sorted = $collection->sortKeys();

$sorted->all();

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

sortKeysDesc() sortKeysDesc()

このメソッドは、sortKeysメソッドと使い方は同じですが、逆順にコレクションをソートします。This method has the same signature as the sortKeys[#method-sortkeys] method, but will sort the collection in the opposite order.

sortKeysUsing() sortKeysUsing()

sortKeysUsingメソッドはコールバックを用いて、連想配列のキーでコレクションをソートします。The sortKeysUsing method sorts the collection by the keys of the underlying associative array using a callback:

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

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

$sorted->all();

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

コールバックは0か、0より小さいか、0より大きい整数を返す比較関数でなければなりません。詳細については、uksortのPHPドキュメントを参照してください。この関数はsortKeysUsingメソッドが内部で利用しているPHP関数です。The callback must be a comparison function that returns an integer less than, equal to, or greater than zero. For more information, refer to the PHP documentation on uksort[https://www.php.net/manual/en/function.uksort.php#refsect1-function.uksort-parameters], which is the PHP function that sortKeysUsing method utilizes internally.

splice() splice()

spliceメソッドは指定したインデックスからアイテムをスライスし、削除し、返します。The splice method removes and returns a slice of items starting at the specified index:

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

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

$chunk->all();

// [3, 4, 5]

$collection->all();

// [1, 2]

結果のコレクションの大きさを限定するために、第２引数を指定できます。You may pass a second argument to limit the size of the resulting collection:

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

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

$chunk->all();

// [3]

$collection->all();

// [1, 2, 4, 5]

さらに、コレクションから削除したアイテムに置き換える、新しいアイテムを第３引数に渡すこともできます。In addition, you may pass a third argument containing the new items to replace the items removed from the 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()

splitメソッドは、コレクションを指定数のグループへ分割します。The split method breaks a collection into the given number of groups:

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

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

$groups->all();

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

splitIn() splitIn()

splitInメソッドは、コレクションを指定された数のグループに分割します。最終グループ以外を完全に埋め、残りを最終グループに割り当てます。The splitIn method breaks a collection into the given number of groups, filling non-terminal groups completely before allocating the remainder to the final group:

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

sumメソッドはコレクションの全アイテムの合計を返します。The sum method returns the sum of all items in the collection:

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

// 15

コレクションがネストした配列やオブジェクトを含んでいる場合、どの値を合計するのを決めるためにキーを指定してください。If the collection contains nested arrays or objects, you should pass a key that will be used to determine which values to sum:

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

$collection->sum('pages');

// 1272

さらに、コレクションのどの項目を合計するのかを決めるためにクロージャを渡すこともできます。In addition, you may pass your own closure to determine which values of the collection to sum:

$collection = collect([
    ['name' => 'Chair', 'colors' => ['Black']],
    ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
    ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
]);

$collection->sum(function ($product) {
    return count($product['colors']);
});

// 6

take() take()

takeメソッドは指定したアイテム数の新しいコレクションを返します。The take method returns a new collection with the specified number of items:

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

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

$chunk->all();

// [0, 1, 2]

アイテム数に負の整数を指定した場合はコレクションの最後から取得します。You may also pass a negative integer to take the specified number of items from the end of the collection:

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

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

$chunk->all();

// [4, 5]

takeUntil() takeUntil()

takeUntilメソッドは、指定のコールバックがtrueを返すまでコレクションのアイテムを返します。The takeUntil method returns items in the collection until the given callback returns true:

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

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

$subset->all();

// [1, 2]

takeUntilメソッドにはシンプルに値を渡すこともでき、その指定値が見つかるまでアイテムを返します。You may also pass a simple value to the takeUntil method to get the items until the given value is found:

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

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

$subset->all();

// [1, 2]

Note: note 指定値が見つからない、もしくはコールバックがtrueを返さない場合、takeUntilメソッドはコレクションの全アイテムを返します。{note} If the given value is not found or the callback never returns true, the takeUntil method will return all items in the collection.

takeWhile() takeWhile()

takeWhileメソッドは、指定のコールバックがfalseを返すまでコレクションのアイテムを返します。The takeWhile method returns items in the collection until the given callback returns false:

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

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

$subset->all();

// [1, 2]

Note: note コールバックがfalseを返さない場合、takeWhileメソッドはコレクション中の全アイテムを返します。{note} If the callback never returns false, the takeWhile method will return all items in the collection.

tap() tap()

tapメソッドは、指定されたコールバックへコレクションを渡します。コレクション自身に影響を与えることなく、その時点のコレクション内容を利用するために使用します。その後、tapメソッドはそのコレクションを返します。The tap method passes the collection to the given callback, allowing you to "tap" into the collection at a specific point and do something with the items while not affecting the collection itself. The collection is then returned by the tap method:

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

// 1

times() times()

静的timesメソッドは指定回数クロージャを呼び出すことで、新しいコレクションを生成します。The static times method creates a new collection by invoking the given closure a specified number of times:

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

$collection->all();

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

toArray() toArray()

toArrayメソッドはコレクションをPHPの「配列」へ変換します。コレクションの値がEloquentモデルの場合は、そのモデルが配列に変換されます。The toArray method converts the collection into a plain PHP array. If the collection's values are Eloquent[/docs/{{version}}/eloquent] models, the models will also be converted to arrays:

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

$collection->toArray();

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

Note: note toArrayは、ネストしたArrayableインスタンスのオブジェクトすべてを配列へ変換します。コレクションの裏の素の配列をそのまま取得したい場合は、代わりにallメソッドを使用してください。{note} toArray also converts all of the collection's nested objects that are an instance of Arrayable to an array. If you want to get the raw array underlying the collection, use the all[#method-all] method instead.

toJson() toJson()

toJsonメソッドはコレクションをシリアライズ済みのJSON文字へ変換します。The toJson method converts the collection into a JSON serialized string:

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

$collection->toJson();

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

transform() transform()

transformメソッドはコレクションを繰り返し処理し、コレクションの各アイテムに指定したコールバックを適用します。コレクション中のアイテムはコールバックから返される値に置き換わります。The transform method iterates over the collection and calls the given callback with each item in the collection. The items in the collection will be replaced by the values returned by the callback:

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

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

$collection->all();

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

Note: note 他のコレクションメソッドとは異なり、transformはコレクション自身を更新します。代わりに新しいコレクションを生成したい場合は、 mapメソッドを使用してください。{note} Unlike most other collection methods, transform modifies the collection itself. If you wish to create a new collection instead, use the map[#method-map] method.

undot() undot()

undot メソッドは、「ドット」記法を用いた一次元のコレクションを多次元のコレクションへ展開します。The undot method expands a single-dimensional collection that uses "dot" notation into a multi-dimensional 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()

unionメソッドは指定した配列をコレクションへ追加します。すでにコレクションにあるキーが、オリジナル配列に含まれている場合は、オリジナルコレクションの値が優先されます。The union method adds the given array to the collection. If the given array contains keys that are already in the original collection, the original collection's values will be preferred:

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

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

$union->all();

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

unique() unique()

uniqueメソッドはコレクションの重複を取り除いた全アイテムを返します。ソート済みのコレクションはオリジナルの配列キーを保っています。下の例ではvaluesメソッドで連続した数字のインデックスにするためリセットしています。The unique method returns all of the unique items in the collection. The returned collection keeps the original array keys, so in the following example we will use the values[#method-values] method to reset the keys to consecutively numbered indexes:

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

$unique = $collection->unique();

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

// [1, 2, 3, 4]

ネストした配列やオブジェクトを取り扱いたい場合は、一意であることを決めるキーを指定する必要があります。When dealing with nested arrays or objects, you may specify the key used to determine uniqueness:

$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メソッドに渡して、アイテムの一意性を決定する値を指定することもできます。Finally, you may also pass your own closure to the unique method to specify which value should determine an item's uniqueness:

$unique = $collection->unique(function ($item) {
    return $item['brand'].$item['type'];
});

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

/*
    [
        ['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'],
        ['name' => 'Apple Watch', 'brand' => 'Apple', 'type' => 'watch'],
        ['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'],
        ['name' => 'Galaxy Gear', 'brand' => 'Samsung', 'type' => 'watch'],
    ]
*/

uniqueメソッドは、アイテムの判定に「緩い」比較を使用します。つまり、同じ値の文字列と整数値は等しいと判定します。「厳密」な比較でフィルタリングしたい場合は、uniqueStrictメソッドを使用してください。The unique method uses "loose" comparisons when checking item values, meaning a string with an integer value will be considered equal to an integer of the same value. Use the uniqueStrict[#method-uniquestrict] method to filter using "strict" comparisons.

lightbulb">Tip!! Eloquentコレクションの使用時は、このメソッドの振る舞いは変わります。{tip} This method's behavior is modified when using Eloquent Collections[/docs/{{version}}/eloquent-collections#method-unique].

uniqueStrict() uniqueStrict()

このメソッドは、uniqueと同じ使用方法です。しかし、全値は「厳密」に比較されます。This method has the same signature as the unique[#method-unique] method; however, all values are compared using "strict" comparisons.

unless() unless()

unlessメソッドは最初の引数がtrueと評価されない場合、コールバックを実行します。The unless method will execute the given callback unless the first argument given to the method evaluates to true:

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

$collection->unless(true, function ($collection) {
    return $collection->push(4);
});

$collection->unless(false, function ($collection) {
    return $collection->push(5);
});

$collection->all();

// [1, 2, 3, 5]

２つ目のコールバックをunlessメソッドへ指定できます。２つ目のコールバックは、unlessメソッドへ渡した最初の引数がtrueと評価されたときに実行します。A second callback may be passed to the unless method. The second callback will be executed when the first argument given to the unless method evaluates to true:

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

$collection->unless(true, function ($collection) {
    return $collection->push(4);
}, function ($collection) {
    return $collection->push(5);
});

$collection->all();

// [1, 2, 3, 5]

unlessの逆の動作は、whenメソッドです。For the inverse of unless, see the when[#method-when] method.

unlessEmpty() unlessEmpty()

whenNotEmptyメソッドのエイリアスです。Alias for the whenNotEmpty[#method-whennotempty] method.

unlessNotEmpty() unlessNotEmpty()

whenEmptyメソッドのエイリアスです。Alias for the whenEmpty[#method-whenempty] method.

unwrap() unwrap()

staticのunwrapメソッドは適用可能な場合、指定値からコレクションの元になっているアイテムを返します。The static unwrap method returns the collection's underlying items from the given value when applicable:

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

// ['John Doe']

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

// ['John Doe']

Collection::unwrap('John Doe');

// 'John Doe'

values() values()

valuesメソッドはキーをリセット後、連続した整数にした新しいコレクションを返します。The values method returns a new collection with the keys reset to consecutive integers:

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

whenメソッドは、メソッドの第１引数がtrueに評価される場合、コールバックを実行します。The when method will execute the given callback when the first argument given to the method evaluates to true:

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

$collection->when(true, function ($collection) {
    return $collection->push(4);
});

$collection->when(false, function ($collection) {
    return $collection->push(5);
});

$collection->all();

// [1, 2, 3, 4]

２つ目のコールバックをwhenメソッドへ指定できます。２番目のコールバックは、whenメソッドへ渡された最初の引数の評価値がfalseになったときに実行します。A second callback may be passed to the when method. The second callback will be executed when the first argument given to the when method evaluates to false:

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

$collection->when(false, function ($collection) {
    return $collection->push(4);
}, function ($collection) {
    return $collection->push(5);
});

$collection->all();

// [1, 2, 3, 5]

whenの逆の動作は、unlessメソッドです。For the inverse of when, see the unless[#method-unless] method.

whenEmpty() whenEmpty()

whenEmptyメソッドは、コレクションが空の場合に、指定したコールバックを実行します。The whenEmpty method will execute the given callback when the collection is empty:

$collection = collect(['Michael', 'Tom']);

$collection->whenEmpty(function ($collection) {
    return $collection->push('Adam');
});

$collection->all();

// ['Michael', 'Tom']


$collection = collect();

$collection->whenEmpty(function ($collection) {
    return $collection->push('Adam');
});

$collection->all();

// ['Adam']

whenEmptyメソッドの２番目のクロージャは、コレクションが空でないときに実行されます。A second closure may be passed to the whenEmpty method that will be executed when the collection is not empty:

$collection = collect(['Michael', 'Tom']);

$collection->whenEmpty(function ($collection) {
    return $collection->push('Adam');
}, function ($collection) {
    return $collection->push('Taylor');
});

$collection->all();

// ['Michael', 'Tom', 'Taylor']

whenEmptyの逆の動作は、whenNotEmptyメソッドです。For the inverse of whenEmpty, see the whenNotEmpty[#method-whennotempty] method.

whenNotEmpty() whenNotEmpty()

whenNotEmptyメソッドは、コレクションが空でない場合に、指定したコールバックを実行します。The whenNotEmpty method will execute the given callback when the collection is not empty:

$collection = collect(['michael', 'tom']);

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

$collection->all();

// ['michael', 'tom', 'adam']


$collection = collect();

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

$collection->all();

// []

whenNotEmptyメソッドに渡される２番目のクロージャは、コレクションが空のときに実行されます。A second closure may be passed to the whenNotEmpty method that will be executed when the collection is empty:

$collection = collect();

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

$collection->all();

// ['taylor']

whenNotEmptyの逆の動作は、whenEmptyメソッドです。For the inverse of whenNotEmpty, see the whenEmpty[#method-whenempty] method.

where() where()

whereメソッドは指定したキー／値ペアでコレクションをフィルタリングします。The where method filters the collection by a given key / value pair:

$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メソッドを使ってください。The where method uses "loose" comparisons when checking item values, meaning a string with an integer value will be considered equal to an integer of the same value. Use the whereStrict[#method-wherestrict] method to filter using "strict" comparisons.

第２引数に比較演算子をオプションとして渡すこともできます。Optionally, you may pass a comparison operator as the second parameter.

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

このメソッドの使用法は、whereメソッドと同じです。しかし、値の比較はすべて「厳格」な比較で行われます。This method has the same signature as the where[#method-where] method; however, all values are compared using "strict" comparisons.

whereBetween() whereBetween()

whereBetweenメソッドは、指定したアイテム値が、指定範囲内にあるかどうかを判断することにより、コレクションをフィルタリングします。The whereBetween method filters the collection by determining if a specified item value is within a given range:

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

whereInメソッドは、指定配列中のアイテム値を持たない要素をコレクションから削除します。The whereIn method removes elements from the collection that do not have a specified item value that is contained within the given array:

$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メソッドを使ってください。The whereIn method uses "loose" comparisons when checking item values, meaning a string with an integer value will be considered equal to an integer of the same value. Use the whereInStrict[#method-whereinstrict] method to filter using "strict" comparisons.

whereInStrict() whereInStrict()

このメソッドの使い方は、whereInメソッドと同じです。違いは全値を「厳密」に比較することです。This method has the same signature as the whereIn[#method-wherein] method; however, all values are compared using "strict" comparisons.

whereInstanceOf() whereInstanceOf()

whereInstanceOfメソッドは、コレクションを指定したクラスタイプによりフィルタリングします。The whereInstanceOf method filters the collection by a given class type:

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

whereNotBetweenメソッドは、指定アイテム値が指定範囲外にあるかどうかを判断することにより、コレクションをフィルタリングします。The whereNotBetween method filters the collection by determining if a specified item value is outside of a given range:

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

WhereNotIn`メソッドは、指定した配列内に含まれる指定項目値を持つ要素を、コレクションから削除します。The whereNotIn method removes elements from the collection that have a specified item value that is contained within the given array:

$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メソッドを使用します。The whereNotIn method uses "loose" comparisons when checking item values, meaning a string with an integer value will be considered equal to an integer of the same value. Use the whereNotInStrict[#method-wherenotinstrict] method to filter using "strict" comparisons.

whereNotInStrict() whereNotInStrict()

このメソッドは、whereNotInと使い方は同じですが、全値の比較が「厳密」に行われる点が異なります。This method has the same signature as the whereNotIn[#method-wherenotin] method; however, all values are compared using "strict" comparisons.

whereNotNull() whereNotNull()

wherenotnullメソッドは、与えられたキーがnullではないアイテムをコレクションから返します。The whereNotNull method returns items from the collection where the given key is not null:

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

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

$filtered->all();

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

whereNull() whereNull()

whernullメソッドは、与えられたキーがnullのアイテムをコレクションから返します。The whereNull method returns items from the collection where the given key is null:

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

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

$filtered->all();

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

wrap() wrap()

staticのwrapメソッドは適用可能であれば、指定値をコレクションでラップします。The static wrap method wraps the given value in a collection when applicable:

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

zipメソッドは指定した配列の値と、対応するインデックスのオリジナルコレクションの値をマージします。The zip method merges together the values of the given array with the values of the original collection at their corresponding index:

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

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

$zipped->all();

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

Higher Order MessageHigher Order Messages

コレクションで繁用するアクションを手短に実行できるよう、"higher order messages"をサポートしました。average、avg、contains、each、every、filter、first、flatMap、groupBy、keyBy、map、max、min、partition、reject、skipUntil、skipWhile、some、sortBy、sortByDesc、sum、unique、takeUntil、takeWhileコレクションメソッドでhigher order messageが使用できます。Collections also provide support for "higher order messages", which are short-cuts for performing common actions on collections. The collection methods that provide higher order messages are: average[#method-average], avg[#method-avg], contains[#method-contains], each[#method-each], every[#method-every], filter[#method-filter], first[#method-first], flatMap[#method-flatmap], groupBy[#method-groupby], keyBy[#method-keyby], map[#method-map], max[#method-max], min[#method-min], partition[#method-partition], reject[#method-reject], skipUntil[#method-skipuntil], skipWhile[#method-skipwhile], some[#method-some], sortBy[#method-sortby], sortByDesc[#method-sortbydesc], sum[#method-sum], takeUntil[#method-takeuntil], takeWhile[#method-takewhile], and unique[#method-unique].

各higher order messageへは、コレクションインスタンスの動的プロパティとしてアクセスできます。例として、コレクション中の各オブジェクトメソッドを呼び出す、each higher order messageを使用してみましょう。Each higher order message can be accessed as a dynamic property on a collection instance. For instance, let's use the each higher order message to call a method on each object within a collection:

use App\Models\User;

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

$users->each->markAsVip();

同様に、ユーザーのコレクションに対し、「投票（votes）」の合計数を求めるために、sum higher order messageを使用できます。Likewise, we can use the sum higher order message to gather the total number of "votes" for a collection of users:

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

return $users->sum->votes;

レイジーコレクションLazy Collections

イントロダクションIntroduction

Note: note Laravelのレイジーコレクションを学ぶ前に、PHPジェネレータに慣れるために時間を取ってください。{note} Before learning more about Laravel's lazy collections, take some time to familiarize yourself with PHP generators[https://www.php.net/manual/en/language.generators.overview.php].

すでに強力なCollectionクラスを補足するために、LazyCollectionクラスはPHPのPHPジェネレータを活用しています。巨大なデータセットをメモリ使用を抑えて利用する目的のためです。To supplement the already powerful Collection class, the LazyCollection class leverages PHP's generators[https://www.php.net/manual/en/language.generators.overview.php] to allow you to work with very large datasets while keeping memory usage low.

たとえば、アプリケーションで数ギガバイトのログを処理する必要があり、ログを解析するためにLaravelのコレクションメソッドを活用するとしましょう。ファイル全体をメモリへ一度で読み込む代わりに、レイジーコレクションなら毎回ファイルの小さな部分だけをメモリに保持するだけで済みます。For example, imagine your application needs to process a multi-gigabyte log file while taking advantage of Laravel's collection methods to parse the logs. Instead of reading the entire file into memory at once, lazy collections may be used to keep only a small part of the file in memory at a given time:

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 ($lines) {
    return LogEntry::fromLines($lines);
})->each(function (LogEntry $logEntry) {
    // ログエントリーの処理…
});

もしくは、10,000個のEloquentモデルを繰り返し処理する必要があると想像してください。今までのLaravelコレクションでは、一度に10,000個のEloquentモデルすべてをメモリーにロードする必要がありました。Or, imagine you need to iterate through 10,000 Eloquent models. When using traditional Laravel collections, all 10,000 Eloquent models must be loaded into memory at the same time:

use App\Models\User;

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

しかし、クエリビルダのcursorメソッドは、LazyCollectionインスタンスを返します。これによりデータベースに対し１つのクエリを実行するだけでなく、一度に１つのEloquentモデルをメモリにロードするだけで済みます。この例では、各ユーザーを個別に繰り返し処理するまでfilterコールバックは実行されず、大幅にメモリ使用量を減らせます。However, the query builder's cursor method returns a LazyCollection instance. This allows you to still only run a single query against the database but also only keep one Eloquent model loaded in memory at a time. In this example, the filter callback is not executed until we actually iterate over each user individually, allowing for a drastic reduction in memory usage:

use App\Models\User;

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

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

レイジーコレクションの生成Creating Lazy Collections

レイジーコレクションインスタンスを生成するには、コレクションのmakeメソッドへPHPジェネレータ関数を渡します。To create a lazy collection instance, you should pass a PHP generator function to the collection's make method:

use Illuminate\Support\LazyCollection;

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

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

Enumerable契約The Enumerable Contract

Collectionクラスのほとんどすべてのメソッドが、LazyCollectionクラス上でも利用できます。両クラスはIlluminate\Support\Enumerable契約を実装しており、以下のメソッドを定義しています。Almost all methods available on the Collection class are also available on the LazyCollection class. Both of these classes implement the Illuminate\Support\Enumerable contract, which defines the following methods:

Note: note shift、pop、prependなどのように、コレクションを変異させるメソッドは、LazyCollectionクラスでは使用できません。{note} Methods that mutate the collection (such as shift, pop, prepend etc.) are not available on the LazyCollection class.

レイジーコレクションメソッドLazy Collection Methods

Enumerable契約で定義しているメソッドに加え、LazyCollectionクラス契約は以下のメソッドを含んでいます。In addition to the methods defined in the Enumerable contract, the LazyCollection class contains the following methods:

takeUntilTimeout() takeUntilTimeout()

takeUntilTimeoutメソッドは、指定された時間まで値を列挙する新しいレイジーコレクションを返します。その後、コレクションは列挙を停止します。The takeUntilTimeout method returns a new lazy collection that will enumerate values until the specified time. After that time, the collection will then stop enumerating:

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

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

    sleep(1);
});

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

このメソッドの使用法を理解するために、カーソルを使用してデータベースから請求書を送信するアプリケーションを想像してみてください。15分ごとに実行され、最大14分間のみ請求書を処理するスケジュール済みタスクを定義できます。To illustrate the usage of this method, imagine an application that submits invoices from the database using a cursor. You could define a scheduled task[/docs/{{version}}/scheduling] that runs every 15 minutes and only processes invoices for a maximum of 14 minutes:

use App\Models\Invoice;
use Illuminate\Support\Carbon;

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

tapEach() tapEach()

eachメソッドはコレクション中の各アイテムに対し、指定したコールバックを即時に呼び出しますが、tapEachメソッドはリストから一つずつアイテムを抜き出し、指定したコールバックを呼び出します。While the each method calls the given callback for each item in the collection right away, the tapEach method only calls the given callback as the items are being pulled out of the list one by one:

// これまでに何もダンプされていない
$lazyCollection = LazyCollection::times(INF)->tapEach(function ($value) {
    dump($value);
});

// ３アイテムがダンプ
$array = $lazyCollection->take(3)->all();

// 1
// 2
// 3

remember() remember()

rememberメソッドは、すでに列挙されている値を記憶し、後続のコレクション列挙でそれらを再度取得しない新しいレイジーコレクションを返します。The remember method returns a new lazy collection that will remember any values that have already been enumerated and will not retrieve them again on subsequent collection enumerations:

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

// クエリは実行された
// 最初の５人のユーザーがデータベースからハイドレイト
$users->take(5)->all();

// 最初の５人のユーザーはコレクションのキャッシュから取得
// 残りはデータベースからハイドレイト
$users->take(20)->all();