コレクション

• イントロダクション
  • コレクションの作成
  • コレクションの拡張
• 利用可能なメソッド
• 高階メッセージ
• 遅延コレクション
  • イントロダクション
  • 遅延コレクションの作成
  • Enumerable契約
  • 遅延コレクションメソッド

イントロダクション

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

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

ご覧のとおり、Collectionクラスを使用すると、メソッドをチェーンして、基になる配列を流暢にマッピングおよび縮小できます。一般的に、コレクションは不変であり、すべてのCollectionメソッドは完全に新しいCollectionインスタンスを返します。

コレクションの作成

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

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

Note

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

コレクションの拡張

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

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

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

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

$upper = $collection->toUpper();

// ['FIRST', 'SECOND']

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

マクロ引数

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

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

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

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

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

利用可能なメソッド

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

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

メソッド一覧

after()

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

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

$collection->after(3);

// 4

$collection->after(5);

// null

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

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

// null

または、最初のアイテムが特定の真理テストに合格するように、独自のクロージャを提供することもできます。

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

// 8

all()

allメソッドは、コレクションによって表される基になる配列を返します。

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

// [1, 2, 3]

average()

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

avg()

avgメソッドは、指定されたキーの平均値を返します。

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

// 20

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

// 2

before()

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

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

$collection->before(3);

// 2

$collection->before(1);

// null

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

// null

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

// 4

chunk()

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

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

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

$chunks->all();

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

このメソッドは、Bootstrapのようなグリッドシステムを使用する際に、ビューで特に便利です。例えば、グリッドに表示したいEloquentモデルのコレクションがあるとします。

@foreach ($products->chunk(3) as $chunk)
    <div class="row">
        @foreach ($chunk as $product)
            <div class="col-xs-4">{{ $product->name }}</div>
        @endforeach
    </div>
@endforeach

chunkWhile()

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

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

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

$chunks->all();

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

collapse()

collapseメソッドは、配列のコレクションを単一のフラットなコレクションに折りたたみます。

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

$collapsed = $collection->collapse();

$collapsed->all();

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

collect()

collectメソッドは、現在コレクション内にあるアイテムを持つ新しいCollectionインスタンスを返します。

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

$collectionB = $collectionA->collect();

$collectionB->all();

// [1, 2, 3]

collectメソッドは主に、遅延コレクションを標準のCollectionインスタンスに変換する際に便利です。

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

$collection = $lazyCollection->collect();

$collection::class;

// 'Illuminate\Support\Collection'

$collection->all();

// [1, 2, 3]

Note

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

combine()

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

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

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

$combined->all();

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

concat()

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

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

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

$concatenated->all();

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

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

contains()

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

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

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

// false

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

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

$collection->contains('Desk');

// true

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

// false

さらに、キーと値のペアをcontainsメソッドに渡して、指定されたペアがコレクション内に存在するかどうかを判断できます。

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

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

// false

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

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

containsOneItem()

containsOneItemメソッドは、コレクションに1つのアイテムが含まれているかどうかを判断します。

collect([])->containsOneItem();

// false

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

// true

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

// false

containsStrict()

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

Note

このメソッドの動作は、Eloquentコレクションを使用する際に変更されます。

count()

countメソッドは、コレクション内のアイテムの総数を返します。

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

$collection->count();

// 4

countBy()

countByメソッドは、コレクション内の値の出現回数をカウントします。デフォルトでは、このメソッドはすべての要素の出現回数をカウントし、コレクション内の特定の「タイプ」の要素をカウントできます。

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

$counted = $collection->countBy();

$counted->all();

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

クロージャをcountByメソッドに渡して、すべてのアイテムをカスタム値でカウントすることもできます。

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

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

$counted->all();

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

crossJoin()

crossJoinメソッドは、コレクションの値を指定された配列またはコレクションの間でクロス結合し、すべての可能な順列を持つデカルト積を返します。

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

$matrix = $collection->crossJoin(['a', 'b']);

$matrix->all();

/*
    [
        [1, 'a'],
        [1, 'b'],
        [2, 'a'],
        [2, 'b'],
    ]
*/

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

$matrix = $collection->crossJoin(['a', 'b'], ['I', 'II']);

$matrix->all();

/*
    [
        [1, 'a', 'I'],
        [1, 'a', 'II'],
        [1, 'b', 'I'],
        [1, 'b', 'II'],
        [2, 'a', 'I'],
        [2, 'a', 'II'],
        [2, 'b', 'I'],
        [2, 'b', 'II'],
    ]
*/

dd()

ddメソッドは、コレクションのアイテムをダンプし、スクリプトの実行を終了します。

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

$collection->dd();

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

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

diff()

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

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

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

$diff->all();

// [1, 3, 5]

Note

このメソッドの動作は、Eloquentコレクションを使用する際に変更されます。

diffAssoc()

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

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

$diff = $collection->diffAssoc([
    'color' => 'yellow',
    'type' => 'fruit',
    'remain' => 3,
    'used' => 6,
]);

$diff->all();

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

diffAssocUsing()

diffAssocとは異なり、diffAssocUsingはインデックスの比較にユーザーが指定したコールバック関数を受け入れます。

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

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

$diff->all();

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

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

diffKeys()

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

$collection = collect([
    'one' => 10,
    'two' => 20,
    'three' => 30,
    'four' => 40,
    'five' => 50,
]);

$diff = $collection->diffKeys([
    'two' => 2,
    'four' => 4,
    'six' => 6,
    'eight' => 8,
]);

$diff->all();

// ['one' => 10, 'three' => 30, 'five' => 50]

doesntContain()

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

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

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

// false

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

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

$collection->doesntContain('Table');

// true

$collection->doesntContain('Desk');

// false

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

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

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

// true

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

dot()

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

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

$flattened = $collection->dot();

$flattened->all();

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

dump()

dumpメソッドは、コレクションのアイテムをダンプします。

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

$collection->dump();

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

コレクションをダンプした後にスクリプトの実行を停止したい場合は、代わりにddメソッドを使用してください。

duplicates()

duplicatesメソッドは、コレクションから重複する値を取得して返します。

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

$collection->duplicates();

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

コレクションに配列またはオブジェクトが含まれている場合、重複する値をチェックしたい属性のキーを渡すことができます。

$employees = collect([
    ['email' => 'abigail@example.com', 'position' => 'Developer'],
    ['email' => 'james@example.com', 'position' => 'Designer'],
    ['email' => 'victoria@example.com', 'position' => 'Developer'],
]);

$employees->duplicates('position');

// [2 => 'Developer']

duplicatesStrict()

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

each()

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

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

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

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

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

eachSpread()

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

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

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

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

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

ensure()

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

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

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

プリミティブ型（string、int、float、bool、array）も指定できます。

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

Warning

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

every()

everyメソッドは、コレクションのすべての要素が指定された真偽テストに合格するかどうかを確認するために使用できます。

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

// false

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

$collection = collect([]);

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

// true

except()

exceptメソッドは、指定されたキーを持つアイテムを除くコレクション内のすべてのアイテムを返します。

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

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

$filtered->all();

// ['product_id' => 1]

exceptの逆は、onlyメソッドを参照してください。

Note

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

filter()

filterメソッドは、指定されたコールバックを使用してコレクションをフィルタリングし、指定された真偽テストに合格したアイテムのみを保持します。

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

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

$filtered->all();

// [3, 4]

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

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

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

// [1, 2, 3]

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

first()

firstメソッドは、指定された真偽テストに合格するコレクション内の最初の要素を返します。

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

// 3

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

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

// 1

firstOrFail()

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

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

// Throws ItemNotFoundException...

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

collect([])->firstOrFail();

// Throws ItemNotFoundException...

firstWhere()

firstWhereメソッドは、指定されたキー/値のペアを持つコレクション内の最初の要素を返します。

$collection = collect([
    ['name' => 'Regena', 'age' => null],
    ['name' => 'Linda', 'age' => 14],
    ['name' => 'Diego', 'age' => 23],
    ['name' => 'Linda', 'age' => 84],
]);

$collection->firstWhere('name', 'Linda');

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

比較演算子を使用してfirstWhereメソッドを呼び出すこともできます。

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

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

whereメソッドと同様に、firstWhereメソッドに1つの引数を渡すことができます。この場合、firstWhereメソッドは、指定されたアイテムキーの値が「真」である最初のアイテムを返します。

$collection->firstWhere('age');

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

flatMap()

flatMapメソッドは、各値をクロージャに渡してコレクションを反復処理します。クロージャは値を自由に変更して返すことができ、その結果は新しいコレクションにマージされます。その後、配列は1レベル平坦化されます。

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

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

$flattened->all();

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

flatMapメソッドは、コレクションを反復処理し、各値を与えられたクロージャに渡します。クロージャはアイテムを自由に変更して返すことができ、それによって変更されたアイテムの新しいコレクションが形成されます。その後、配列は1レベル平坦化されます。

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

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

$flattened->all();

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

flatten()

flattenメソッドは、多次元コレクションを1次元に平坦化します。

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

$flattened = $collection->flatten();

$flattened->all();

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

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

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

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

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

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

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

flip()

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

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

$flipped = $collection->flip();

$flipped->all();

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

forget()

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

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

// 単一のキーを忘れる...
$collection->forget('name');

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

// 複数のキーを忘れる...
$collection->forget(['name', 'framework']);

// []

Warning

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

forPage()

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

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

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

$chunk->all();

// [4, 5, 6]

get()

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

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

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

// taylor

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

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

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

// 34

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

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

// taylor@example.com

groupBy()

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

$collection = collect([
    ['account_id' => 'account-x10', 'product' => 'Chair'],
    ['account_id' => 'account-x10', 'product' => 'Bookcase'],
    ['account_id' => 'account-x11', 'product' => 'Desk'],
]);

$grouped = $collection->groupBy('account_id');

$grouped->all();

/*
    [
        'account-x10' => [
            ['account_id' => 'account-x10', 'product' => 'Chair'],
            ['account_id' => 'account-x10', 'product' => 'Bookcase'],
        ],
        'account-x11' => [
            ['account_id' => 'account-x11', 'product' => 'Desk'],
        ],
    ]
*/

文字列のkeyを渡す代わりに、コールバックを渡すことができます。コールバックは、グループ化するキーとして返す値を返すべきです。

$grouped = $collection->groupBy(function (array $item, int $key) {
    return substr($item['account_id'], -3);
});

$grouped->all();

/*
    [
        'x10' => [
            ['account_id' => 'account-x10', 'product' => 'Chair'],
            ['account_id' => 'account-x10', 'product' => 'Bookcase'],
        ],
        'x11' => [
            ['account_id' => 'account-x11', 'product' => 'Desk'],
        ],
    ]
*/

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

$data = new Collection([
    10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
    20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
    30 => ['user' => 3, 'skill' => 2, 'roles' => ['Role_1']],
    40 => ['user' => 4, 'skill' => 2, 'roles' => ['Role_2']],
]);

$result = $data->groupBy(['skill', function (array $item) {
    return $item['roles'];
}], preserveKeys: true);

/*
[
    1 => [
        'Role_1' => [
            10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
            20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
        ],
        'Role_2' => [
            20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
        ],
        'Role_3' => [
            10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
        ],
    ],
    2 => [
        'Role_1' => [
            30 => ['user' => 3, 'skill' => 2, 'roles' => ['Role_1']],
        ],
        'Role_2' => [
            40 => ['user' => 4, 'skill' => 2, 'roles' => ['Role_2']],
        ],
    ],
];
*/

has()

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

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

$collection->has('product');

// true

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

// true

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

// false

hasAny()

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

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

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

// true

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

// false

implode()

implodeメソッドは、コレクション内のアイテムを結合します。その引数は、コレクション内のアイテムのタイプに依存します。コレクションに配列またはオブジェクトが含まれている場合、結合したい属性のキーと、値の間に配置したい「接着剤」文字列を渡す必要があります。

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

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

// Desk, Chair

コレクションに単純な文字列または数値が含まれている場合、メソッドに「接着剤」を唯一の引数として渡すだけです。

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

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

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

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

// DESK, CHAIR

intersect()

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

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

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

$intersect->all();

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

Note

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

intersectAssoc()

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

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

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

$intersect->all();

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

intersectByKeys()

intersectByKeysメソッドは、元のコレクションから指定されたarrayまたはコレクションに存在しないキーとそれに対応する値を削除します。

$collection = collect([
    'serial' => 'UX301', 'type' => 'screen', 'year' => 2009,
]);

$intersect = $collection->intersectByKeys([
    'reference' => 'UX404', 'type' => 'tab', 'year' => 2011
]);

$intersect->all();

// ['type' => 'screen', 'year' => 2009]

$intersect = $collection->intersectByKeys([
    'reference' => 'UX404', 'type' => 'tab', 'year' => 2011,
]);

$intersect->all();

// ['type' => 'screen', 'year' => 2009]

isEmpty()

isEmptyメソッドは、コレクションが空の場合にtrueを返し、そうでない場合はfalseを返します。

collect([])->isEmpty();

// true

isNotEmpty()

isNotEmptyメソッドは、コレクションが空でない場合にtrueを返し、そうでない場合はfalseを返します。

collect([])->isNotEmpty();

// false

join()

joinメソッドは、コレクションの値を文字列で結合します。このメソッドの第二引数を使用して、最後の要素の後に追加する方法を指定することもできます。

collect(['a', 'b', 'c'])->join(', '); // 'a, b, c'
collect(['a', 'b', 'c'])->join(', ', ', and '); // 'a, b, and c'
collect(['a', 'b'])->join(', ', ' and '); // 'a and b'
collect(['a'])->join(', ', ' and '); // 'a'
collect([])->join(', ', ' and '); // ''

keyBy()

keyByメソッドは、指定されたキーでコレクションをキー付けします。複数のアイテムが同じキーを持つ場合、新しいコレクションには最後のアイテムのみが表示されます。

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

$keyed = $collection->keyBy('product_id');

$keyed->all();

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

メソッドにコールバックを渡すこともできます。コールバックは、コレクションのキーとする値を返す必要があります。

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

$keyed->all();

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

keys()

keysメソッドは、コレクションのすべてのキーを返します。

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

$keys = $collection->keys();

$keys->all();

// ['prod-100', 'prod-200']

last()

lastメソッドは、指定された真偽テストを通過するコレクションの最後の要素を返します。

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

// 2

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

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

// 4

lazy()

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

$lazyCollection = collect([1, 2, 3, 4])->lazy();

$lazyCollection::class;

// Illuminate\Support\LazyCollection

$lazyCollection->all();

// [1, 2, 3, 4]

これは、膨大な数のアイテムを含むCollectionに対して変換を行う必要がある場合に特に便利です。

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

コレクションをLazyCollectionに変換することで、大量の追加メモリを割り当てることを回避できます。元のコレクションは依然としてメモリ内に値を保持しますが、後続のフィルターはそうではありません。したがって、コレクションの結果をフィルタリングする際に、事実上追加のメモリは割り当てられません。

macro()

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

make()

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

map()

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

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

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

$multiplied->all();

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

Warning

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

mapInto()

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

class Currency
{
    /**
     * 新しい通貨インスタンスを作成します。
     */
    function __construct(
        public string $code,
    ) {}
}

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

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

$currencies->all();

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

mapSpread()

mapSpreadメソッドは、コレクションのアイテムを反復処理し、各ネストされたアイテムの値を指定されたクロージャに渡します。クロージャはアイテムを自由に変更して返すことができ、変更されたアイテムの新しいコレクションを形成します。

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

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

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

$sequence->all();

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

mapToGroups()

mapToGroupsメソッドは、指定されたクロージャによってコレクションのアイテムをグループ化します。クロージャは、単一のキー/値ペアを含む連想配列を返す必要があり、グループ化された値の新しいコレクションを形成します。

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

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

$grouped->all();

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

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

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

mapWithKeys()

mapWithKeysメソッドは、コレクション全体を反復処理し、各値を指定されたクロージャに渡します。クロージャは、単一のキー/値ペアを含む連想配列を返す必要があります。

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

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

$keyed->all();

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

max()

maxメソッドは、指定されたキーの最大値を返します。

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

// 20

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

// 5

median()

medianメソッドは、指定されたキーの中央値を返します。

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

// 15

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

// 1.5

merge()

mergeメソッドは、指定された配列またはコレクションを元のコレクションとマージします。指定されたアイテムの文字列キーが元のコレクションの文字列キーと一致する場合、指定されたアイテムの値は元のコレクションの値を上書きします。

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

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

$merged->all();

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

指定されたアイテムのキーが数値の場合、値はコレクションの末尾に追加されます。

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

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

$merged->all();

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

mergeRecursive()

mergeRecursiveメソッドは、指定された配列またはコレクションを元のコレクションと再帰的にマージします。指定されたアイテムの文字列キーが元のコレクションの文字列キーと一致する場合、これらのキーの値は配列にマージされ、これは再帰的に行われます。

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

```php
$merged = $collection->mergeRecursive([
    'product_id' => 2,
    'price' => 200,
    'discount' => false
]);

$merged->all();

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

min()

minメソッドは、指定されたキーの最小値を返します。

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

// 10

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

// 1

mode()

modeメソッドは、指定されたキーの最頻値を返します。

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

// [10]

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

// [1]

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

// [1, 2]

multiply()

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

$users = collect([
    ['name' => 'User #1', 'email' => 'user1@example.com'],
    ['name' => 'User #2', 'email' => 'user2@example.com'],
])->multiply(3);

/*
    [
        ['name' => 'User #1', 'email' => 'user1@example.com'],
        ['name' => 'User #2', 'email' => 'user2@example.com'],
        ['name' => 'User #1', 'email' => 'user1@example.com'],
        ['name' => 'User #2', 'email' => 'user2@example.com'],
        ['name' => 'User #1', 'email' => 'user1@example.com'],
        ['name' => 'User #2', 'email' => 'user2@example.com'],
    ]
*/

nth()

nthメソッドは、n番目ごとの要素で構成される新しいコレクションを作成します。

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

$collection->nth(4);

// ['a', 'e']

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

$collection->nth(4, 1);

// ['b', 'f']

only()

onlyメソッドは、指定されたキーを持つコレクション内のアイテムを返します。

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

$filtered = $collection->only(['product_id', 'name']);

$filtered->all();

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

onlyの逆は、exceptメソッドを参照してください。

Note

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

pad()

padメソッドは、配列が指定されたサイズに達するまで、指定された値で配列を埋めます。このメソッドは、array_pad PHP関数のように動作します。

左側にパディングするには、負のサイズを指定する必要があります。指定されたサイズの絶対値が配列の長さ以下の場合、パディングは行われません。

$collection = collect(['A', 'B', 'C']);

$filtered = $collection->pad(5, 0);

$filtered->all();

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

$filtered = $collection->pad(-5, 0);

$filtered->all();

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

partition()

partitionメソッドは、PHPの配列の分割と組み合わせて使用し、指定された真偽テストに合格する要素とそうでない要素を分離できます。

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

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

$underThree->all();

// [1, 2]

$equalOrAboveThree->all();

// [3, 4, 5, 6]

percentage()

percentageメソッドは、指定された真偽テストに合格するコレクション内のアイテムの割合を素早く決定するために使用できます。

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

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

// 33.33

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

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

// 33.333

pipe()

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

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

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

// 6

pipeInto()

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

class ResourceCollection
{
    /**
     * Create a new ResourceCollection instance.
     */
    public function __construct(
        public Collection $collection,
    ) {}
}

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

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

$resource->collection->all();

// [1, 2, 3]

pipeThrough()

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

use Illuminate\Support\Collection;

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

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

// 15

pluck()

pluckメソッドは、指定されたキーのすべての値を取得します。

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

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

$plucked->all();

// ['Desk', 'Chair']

結果のコレクションをどのようにキー付けするかを指定することもできます。

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

$plucked->all();

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

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

$collection = collect([
    [
        'name' => 'Laracon',
        'speakers' => [
            'first_day' => ['Rosa', 'Judith'],
        ],
    ],
    [
        'name' => 'VueConf',
        'speakers' => [
            'first_day' => ['Abigail', 'Joey'],
        ],
    ],
]);

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

$plucked->all();

// [['Rosa', 'Judith'], ['Abigail', 'Joey']]

もし重複するキーが存在する場合、最後に一致した要素が取得されたコレクションに挿入されます。

$collection = collect([
    ['brand' => 'Tesla',  'color' => 'red'],
    ['brand' => 'Pagani', 'color' => 'white'],
    ['brand' => 'Tesla',  'color' => 'black'],
    ['brand' => 'Pagani', 'color' => 'orange'],
]);

$plucked = $collection->pluck('color', 'brand');

$plucked->all();

// ['Tesla' => 'black', 'Pagani' => 'orange']

pop()

popメソッドは、コレクションの最後のアイテムを削除して返します。

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

$collection->pop();

// 5

$collection->all();

// [1, 2, 3, 4]

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

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

$collection->pop(3);

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

$collection->all();

// [1, 2]

prepend()

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

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

$collection->prepend(0);

$collection->all();

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

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

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

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

$collection->all();

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

pull()

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

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

$collection->pull('name');

// 'Desk'

$collection->all();

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

push()

pushメソッドは、コレクションの末尾にアイテムを追加します。

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

$collection->push(5);

$collection->all();

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

put()

putメソッドは、指定されたキーと値をコレクションに設定します。

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

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

$collection->all();

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

random()

randomメソッドは、コレクションからランダムにアイテムを返します。

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

$collection->random();

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

randomメソッドに整数を渡すことで、ランダムに複数のアイテムを取得することができます。常にアイテムのコレクションが返されます。

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

$random->all();

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

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

randomメソッドはクロージャも受け付けます。このクロージャは現在のコレクションインスタンスを受け取ります：

use Illuminate\Support\Collection;

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

$random->all();

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

range()

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

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

$collection->all();

// [3, 4, 5, 6]

reduce()

reduceメソッドは、コレクションを単一の値に縮小し、各反復の結果を後続の反復に渡します：

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

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

// 6

最初の反復での$carryの値はnullですが、reduceに第二引数を渡すことで初期値を指定できます：

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

// 10

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

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

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

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

// 4264

reduceSpread()

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

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

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

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

reject()

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

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

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

$filtered->all();

// [1, 2]

rejectメソッドの逆の動作をする場合は、filterメソッドを参照してください。

replace()

replaceメソッドはmergeと同様に動作しますが、文字列キーを持つ一致するアイテムを上書きするだけでなく、一致する数値キーを持つコレクション内のアイテムも上書きします：

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

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

$replaced->all();

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

replaceRecursive()

このメソッドはreplaceのように動作しますが、配列に再帰的に入り込み、同じ置換プロセスを内部の値に適用します：

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

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

$replaced->all();

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

reverse()

reverseメソッドは、コレクションのアイテムの順序を逆にし、元のキーを保持します：

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

$reversed = $collection->reverse();

$reversed->all();

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

search()

searchメソッドは、指定された値をコレクション内で検索し、見つかった場合はそのキーを返します。アイテムが見つからない場合はfalseを返します：

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

$collection->search(4);

// 1

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

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

// false

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

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

// 2

select()

selectメソッドは、SQLのSELECT文のように、指定されたキーをコレクションから選択します：

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

$users->select(['name', 'role']);

/*
    [
        ['name' => 'Taylor Otwell', 'role' => 'Developer'],
        ['name' => 'Victoria Faith', 'role' => 'Researcher'],
    ],
*/

shift()

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

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

$collection->shift();

// 1

$collection->all();

// [2, 3, 4, 5]

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

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

$collection->shift(3);

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

$collection->all();

// [4, 5]

shuffle()

shuffleメソッドは、コレクション内のアイテムをランダムにシャッフルします：

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

$shuffled = $collection->shuffle();

$shuffled->all();

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

skip()

skipメソッドは、指定された数の要素をコレクションの先頭から削除した新しいコレクションを返します：

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

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

$collection->all();

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

skipUntil()

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

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

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

$subset->all();

// [3, 4]

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

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

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

$subset->all();

// [3, 4]

Warning

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

skipWhile()

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

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

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

$subset->all();

// [4]

Warning

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

slice()

sliceメソッドは、指定されたインデックスから始まるコレクションのスライスを返します：

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

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

$slice->all();

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

返されるスライスのサイズを制限したい場合は、メソッドの第二引数に希望のサイズを渡します：

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

$slice->all();

// [5, 6]

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

sliding()

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

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

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

$chunks->toArray();

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

これは特にeachSpreadメソッドと組み合わせて使用する場合に便利です：

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

オプションで、各チャンクの最初のアイテム間の距離を決定する「ステップ」値を第二引数に渡すこともできます：

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

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

$chunks->toArray();

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

sole()

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

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

// 2

soleメソッドにキー/値のペアを渡すこともできます。これにより、指定されたペアに完全に一致する最初の要素が返されますが、一致する要素がちょうど1つの場合に限ります。

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

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

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

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

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

$collection->sole();

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

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

some()

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

sort()

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

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

$sorted = $collection->sort();

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

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

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

Note

ネストされた配列やオブジェクトのコレクションをソートする必要がある場合は、sortByおよびsortByDescメソッドを参照してください。

sortBy()

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

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

$sorted = $collection->sortBy('price');

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

/*
    [
        ['name' => 'Chair', 'price' => 100],
        ['name' => 'Bookcase', 'price' => 150],
        ['name' => 'Desk', 'price' => 200],
    ]
*/

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

$collection = collect([
    ['title' => 'Item 1'],
    ['title' => 'Item 12'],
    ['title' => 'Item 3'],
]);

$sorted = $collection->sortBy('title', SORT_NATURAL);

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

/*
    [
        ['title' => 'Item 1'],
        ['title' => 'Item 3'],
        ['title' => 'Item 12'],
    ]
*/

また、コレクションの値をどのようにソートするかを決定する独自のクロージャを渡すこともできます。

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

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

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

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

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

$collection = collect([
    ['name' => 'Taylor Otwell', 'age' => 34],
    ['name' => 'Abigail Otwell', 'age' => 30],
    ['name' => 'Taylor Otwell', 'age' => 36],
    ['name' => 'Abigail Otwell', 'age' => 32],
]);

$sorted = $collection->sortBy([
    ['name', 'asc'],
    ['age', 'desc'],
]);

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

/*
    [
        ['name' => 'Abigail Otwell', 'age' => 32],
        ['name' => 'Abigail Otwell', 'age' => 30],
        ['name' => 'Taylor Otwell', 'age' => 36],
        ['name' => 'Taylor Otwell', 'age' => 34],
    ]
*/

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

$collection = collect([
    ['name' => 'Taylor Otwell', 'age' => 34],
    ['name' => 'Abigail Otwell', 'age' => 30],
    ['name' => 'Taylor Otwell', 'age' => 36],
    ['name' => 'Abigail Otwell', 'age' => 32],
]);

$sorted = $collection->sortBy([
    fn (array $a, array $b) => $a['name'] <=> $b['name'],
    fn (array $a, array $b) => $b['age'] <=> $a['age'],
]);

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

/*
    [
        ['name' => 'Abigail Otwell', 'age' => 32],
        ['name' => 'Abigail Otwell', 'age' => 30],
        ['name' => 'Taylor Otwell', 'age' => 36],
        ['name' => 'Taylor Otwell', 'age' => 34],
    ]
*/

sortByDesc()

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

sortDesc()

このメソッドはsortメソッドとは逆の順序でコレクションをソートします。

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

$sorted = $collection->sortDesc();

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

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

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

sortKeys()

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

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

$sorted = $collection->sortKeys();

$sorted->all();

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

sortKeysDesc()

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

sortKeysUsing()

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

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

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

$sorted->all();

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

コールバックは、ゼロ未満、ゼロ、またはゼロより大きい整数を返す比較関数である必要があります。詳細については、sortKeysUsingメソッドが内部的に利用しているPHPのuksortに関するドキュメントを参照してください。

splice()

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

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

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

$chunk->all();

// [3, 4, 5]

$collection->all();

// [1, 2]

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

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

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

$chunk->all();

// [3]

$collection->all();

// [1, 2, 4, 5]

さらに、コレクションから削除されたアイテムを置き換える新しいアイテムを含む3番目の引数を渡すことができます。

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

$chunk = $collection->splice(2, 1, [10, 11]);

$chunk->all();

// [3]

$collection->all();

// [1, 2, 10, 11, 4, 5]

split()

splitメソッドは、コレクションを指定された数のグループに分割します。

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

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

$groups->all();

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

splitIn()

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

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

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

$groups->all();

// [[1, 2, 3, 4], [5, 6, 7, 8], [9, 10]]

sum()

sumメソッドは、コレクション内のすべてのアイテムの合計を返します。

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

// 15

コレクションにネストされた配列やオブジェクトが含まれている場合、合計する値を決定するためにキーを渡す必要があります。

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

$collection->sum('pages');

// 1272

``` さらに、コレクションのどの値を合計するかを決定するために、独自のクロージャを渡すこともできます。 $collection = collect([ ['name' => 'Chair', 'colors' => ['Black']], ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']], ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']], ]); $collection->sum(function (array $product) { return count($product['colors']); }); // 6

take()

takeメソッドは、指定された数のアイテムを持つ新しいコレクションを返します。 $collection = collect([0, 1, 2, 3, 4, 5]); $chunk = $collection->take(3); $chunk->all(); // [0, 1, 2] また、負の整数を渡して、コレクションの末尾から指定された数のアイテムを取得することもできます。 $collection = collect([0, 1, 2, 3, 4, 5]); $chunk = $collection->take(-2); $chunk->all(); // [4, 5]

takeUntil()

takeUntilメソッドは、指定されたコールバックがtrueを返すまでコレクション内のアイテムを返します。 $collection = collect([1, 2, 3, 4]); $subset = $collection->takeUntil(function (int $item) { return $item >= 3; }); $subset->all(); // [1, 2] また、takeUntilメソッドに単純な値を渡して、指定された値が見つかるまでアイテムを取得することもできます。 $collection = collect([1, 2, 3, 4]); $subset = $collection->takeUntil(3); $subset->all(); // [1, 2]

Warning

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

takeWhile()

takeWhileメソッドは、指定されたコールバックがfalseを返すまでコレクション内のアイテムを返します。 $collection = collect([1, 2, 3, 4]); $subset = $collection->takeWhile(function (int $item) { return $item < 3; }); $subset->all(); // [1, 2]

Warning

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

tap()

tapメソッドは、指定されたコールバックにコレクションを渡し、コレクションの特定のポイントでアイテムを操作できるようにしますが、コレクション自体には影響を与えません。その後、tapメソッドによってコレクションが返されます。 collect([2, 4, 3, 1, 5]) ->sort() ->tap(function (Collection $collection) { Log::debug('Values after sorting', $collection->values()->all()); }) ->shift(); // 1

times()

静的なtimesメソッドは、指定された回数だけ指定されたクロージャを呼び出すことで、新しいコレクションを作成します。 $collection = Collection::times(10, function (int $number) { return $number * 9; }); $collection->all(); // [9, 18, 27, 36, 45, 54, 63, 72, 81, 90]

toArray()

toArrayメソッドは、コレクションをプレーンなPHPのarrayに変換します。コレクションの値がEloquentモデルの場合、モデルも配列に変換されます。 $collection = collect(['name' => 'Desk', 'price' => 200]); $collection->toArray(); / [ ['name' => 'Desk', 'price' => 200], ] /

Warning

toArrayは、コレクションのすべてのネストされたオブジェクトをArrayableのインスタンスである場合に配列に変換します。コレクションの基になる生の配列を取得したい場合は、代わりにallメソッドを使用してください。

toJson()

toJsonメソッドは、コレクションをJSONシリアライズされた文字列に変換します。 $collection = collect(['name' => 'Desk', 'price' => 200]); $collection->toJson(); // '{"name":"Desk", "price":200}'

transform()

transformメソッドは、コレクションを反復処理し、指定されたコールバックをコレクション内の各アイテムに対して呼び出します。コレクション内のアイテムは、コールバックによって返される値に置き換えられます。 $collection = collect([1, 2, 3, 4, 5]); $collection->transform(function (int $item, int $key) { return $item * 2; }); $collection->all(); // [2, 4, 6, 8, 10]

Warning

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

undot()

undotメソッドは、"ドット"記法を使用した単一の次元のコレクションを多次元のコレクションに展開します。 $person = collect([ 'name.first_name' => 'Marie', 'name.last_name' => 'Valentine', 'address.line_1' => '2992 Eagle Drive', 'address.line_2' => '', 'address.suburb' => 'Detroit', 'address.state' => 'MI', 'address.postcode' => '48219' ]); $person = $person->undot(); $person->toArray(); / [ "name" => [ "first_name" => "Marie", "last_name" => "Valentine", ], "address" => [ "line_1" => "2992 Eagle Drive", "line_2" => "", "suburb" => "Detroit", "state" => "MI", "postcode" => "48219", ], ] /

union()

unionメソッドは、指定された配列をコレクションに追加します。指定された配列に元のコレクションに既に存在するキーが含まれている場合、元のコレクションの値が優先されます。 $collection = collect([1 => ['a'], 2 => ['b']]); $union = $collection->union([3 => ['c'], 1 => ['d']]); $union->all(); // [1 => ['a'], 2 => ['b'], 3 => ['c']]

unique()

uniqueメソッドは、コレクション内のすべての一意のアイテムを返します。返されるコレクションは元の配列のキーを保持するため、次の例ではvaluesメソッドを使用してキーを連続した番号のインデックスにリセットしています。 $collection = collect([1, 1, 2, 2, 3, 4, 2]); $unique = $collection->unique(); $unique->values()->all(); // [1, 2, 3, 4] ネストされた配列やオブジェクトを扱う場合、一意性を決定するために使用するキーを指定できます。 $collection = collect([ ['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'], ['name' => 'iPhone 5', 'brand' => 'Apple', 'type' => 'phone'], ['name' => 'Apple Watch', 'brand' => 'Apple', 'type' => 'watch'], ['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'], ['name' => 'Galaxy Gear', 'brand' => 'Samsung', 'type' => 'watch'], ]); $unique = $collection->unique('brand'); $unique->values()->all(); / [ ['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'], ['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'], ] / 最後に、アイテムの一意性を決定する値を指定するために、独自のクロージャをuniqueメソッドに渡すこともできます。 $unique = $collection->unique(function (array $item) { return $item['brand'].$item['type']; }); $unique->values()->all(); / [ ['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'], ['name' => 'Apple Watch', 'brand' => 'Apple', 'type' => 'watch'], ['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'], ['name' => 'Galaxy Gear', 'brand' => 'Samsung', 'type' => 'watch'], ] / uniqueメソッドは、アイテムの値をチェックする際に"緩い"比較を使用します。つまり、整数値を持つ文字列は、同じ値の整数と等しいと見なされます。"厳密な"比較を使用してフィルタリングするには、uniqueStrictメソッドを使用してください。

Note

このメソッドの動作は、Eloquentコレクションを使用する際に変更されます。

uniqueStrict()

このメソッドは、uniqueメソッドと同じシグネチャを持ちます。ただし、すべての値は"厳密な"比較を使用して比較されます。

unless()

unlessメソッドは、メソッドに与えられた最初の引数がtrueと評価されない限り、指定されたコールバックを実行します。 $collection = collect([1, 2, 3]); $collection->unless(true, function (Collection $collection) { return $collection->push(4); }); $collection->unless(false, function (Collection $collection) { return $collection->push(5); }); $collection->all(); // [1, 2, 3, 5] unlessメソッドには、2番目のコールバックを渡すこともできます。2番目のコールバックは、unlessメソッドに与えられた最初の引数がtrueと評価された場合に実行されます。 $collection = collect([1, 2, 3]); $collection->unless(true, function (Collection $collection) { return $collection->push(4); }, function (Collection $collection) { return $collection->push(5); }); $collection->all(); // [1, 2, 3, 5] unlessの逆の動作については、whenメソッドを参照してください。

unlessEmpty()

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

unlessNotEmpty()

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

unwrap()

静的なunwrapメソッドは、適用可能な場合に、指定された値からコレクションの基になるアイテムを返します。 Collection::unwrap(collect('John Doe')); // ['John Doe'] Collection::unwrap(['John Doe']); // ['John Doe'] Collection::unwrap('John Doe'); // 'John Doe'

value()

valueメソッドは、コレクションの最初の要素から指定された値を取得します。 $collection = collect([ ['product' => 'Desk', 'price' => 200], ['product' => 'Speaker', 'price' => 400], ]); $value = $collection->value('price'); // 200

values()

valuesメソッドは、キーが連続した整数にリセットされた新しいコレクションを返します。 $collection = collect([ 10 => ['product' => 'Desk', 'price' => 200], 11 => ['product' => 'Desk', 'price' => 200], ]); $values = $collection->values(); $values->all(); / [ 0 => ['product' => 'Desk', 'price' => 200], 1 => ['product' => 'Desk', 'price' => 200], ] /

when()

whenメソッドは、メソッドに渡された最初の引数がtrueと評価された場合、指定されたコールバックを実行します。コレクションインスタンスとwhenメソッドに渡された最初の引数がクロージャに提供されます。 $collection = collect([1, 2, 3]); $collection->when(true, function (Collection $collection, int $value) { return $collection->push(4); }); $collection->when(false, function (Collection $collection, int $value) { return $collection->push(5); }); $collection->all(); // [1, 2, 3, 4] whenメソッドには、2番目のコールバックを渡すこともできます。この2番目のコールバックは、whenメソッドに渡された最初の引数がfalseと評価された場合に実行されます。 $collection = collect([1, 2, 3]); $collection->when(false, function (Collection $collection, int $value) { return $collection->push(4); }, function (Collection $collection) { return $collection->push(5); }); $collection->all(); // [1, 2, 3, 5] whenの逆の動作については、unlessメソッドを参照してください。

whenEmpty()

whenEmptyメソッドは、コレクションが空の場合に指定されたコールバックを実行します。 $collection = collect(['Michael', 'Tom']); $collection->whenEmpty(function (Collection $collection) { return $collection->push('Adam'); }); $collection->all(); // ['Michael', 'Tom'] $collection = collect(); $collection->whenEmpty(function (Collection $collection) { return $collection->push('Adam'); }); $collection->all(); // ['Adam'] whenEmptyメソッドには、2番目のクロージャを渡すこともできます。この2番目のクロージャは、コレクションが空でない場合に実行されます。 $collection = collect(['Michael', 'Tom']); $collection->whenEmpty(function (Collection $collection) { return $collection->push('Adam'); }, function (Collection $collection) { return $collection->push('Taylor'); }); $collection->all(); // ['Michael', 'Tom', 'Taylor'] whenEmptyの逆の動作については、whenNotEmptyメソッドを参照してください。

whenNotEmpty()

whenNotEmptyメソッドは、コレクションが空でない場合に指定されたコールバックを実行します。 $collection = collect(['michael', 'tom']); $collection->whenNotEmpty(function (Collection $collection) { return $collection->push('adam'); }); $collection->all(); // ['michael', 'tom', 'adam'] $collection = collect(); $collection->whenNotEmpty(function (Collection $collection) { return $collection->push('adam'); }); $collection->all(); // [] whenNotEmptyメソッドには、2番目のクロージャを渡すこともできます。この2番目のクロージャは、コレクションが空の場合に実行されます。 $collection = collect(); $collection->whenNotEmpty(function (Collection $collection) { return $collection->push('adam'); }, function (Collection $collection) { return $collection->push('taylor'); }); $collection->all(); // ['taylor'] whenNotEmptyの逆の動作については、whenEmptyメソッドを参照してください。

where()

whereメソッドは、指定されたキー/値のペアでコレクションをフィルタリングします。 $collection = collect([ ['product' => 'Desk', 'price' => 200], ['product' => 'Chair', 'price' => 100], ['product' => 'Bookcase', 'price' => 150], ['product' => 'Door', 'price' => 100], ]); $filtered = $collection->where('price', 100); $filtered->all(); / [ ['product' => 'Chair', 'price' => 100], ['product' => 'Door', 'price' => 100], ] / whereメソッドは、アイテムの値をチェックする際に「緩い」比較を使用します。つまり、整数値を持つ文字列は、同じ値の整数と等しいとみなされます。「厳密な」比較を使用してフィルタリングするには、whereStrictメソッドを使用してください。 オプションとして、比較演算子を2番目のパラメータとして渡すことができます。サポートされている演算子は、'===', '!==', '!=', '==', '=', '<>', '>', '<', '>=', '<='です。 $collection = collect([ ['name' => 'Jim', 'deleted_at' => '2019-01-01 00:00:00'], ['name' => 'Sally', 'deleted_at' => '2019-01-02 00:00:00'], ['name' => 'Sue', 'deleted_at' => null], ]); $filtered = $collection->where('deleted_at', '!=', null); $filtered->all(); / [ ['name' => 'Jim', 'deleted_at' => '2019-01-01 00:00:00'], ['name' => 'Sally', 'deleted_at' => '2019-01-02 00:00:00'], ] /

whereStrict()

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

whereBetween()

whereBetweenメソッドは、指定されたアイテムの値が指定された範囲内にあるかどうかを判断して、コレクションをフィルタリングします。 $collection = collect([ ['product' => 'Desk', 'price' => 200], ['product' => 'Chair', 'price' => 80], ['product' => 'Bookcase', 'price' => 150], ['product' => 'Pencil', 'price' => 30], ['product' => 'Door', 'price' => 100], ]); $filtered = $collection->whereBetween('price', [100, 200]); $filtered->all(); / [ ['product' => 'Desk', 'price' => 200], ['product' => 'Bookcase', 'price' => 150], ['product' => 'Door', 'price' => 100], ] /

whereIn()

whereInメソッドは、指定されたアイテムの値が指定された配列に含まれていない要素をコレクションから削除します。 $collection = collect([ ['product' => 'Desk', 'price' => 200], ['product' => 'Chair', 'price' => 100], ['product' => 'Bookcase', 'price' => 150], ['product' => 'Door', 'price' => 100], ]); $filtered = $collection->whereIn('price', [150, 200]); $filtered->all(); / [ ['product' => 'Desk', 'price' => 200], ['product' => 'Bookcase', 'price' => 150], ] / whereInメソッドは、アイテムの値をチェックする際に「緩い」比較を使用します。つまり、整数値を持つ文字列は、同じ値の整数と等しいとみなされます。「厳密な」比較を使用してフィルタリングするには、whereInStrictメソッドを使用してください。

whereInStrict()

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

whereInstanceOf()

whereInstanceOfメソッドは、指定されたクラスタイプでコレクションをフィルタリングします。 use App\Models\User; use App\Models\Post; $collection = collect([ new User, new User, new Post, ]); $filtered = $collection->whereInstanceOf(User::class); $filtered->all(); // [App\Models\User, App\Models\User]

whereNotBetween()

whereNotBetweenメソッドは、指定されたアイテムの値が指定された範囲外にあるかどうかを判断して、コレクションをフィルタリングします。 $collection = collect([ ['product' => 'Desk', 'price' => 200], ['product' => 'Chair', 'price' => 80], ['product' => 'Bookcase', 'price' => 150], ['product' => 'Pencil', 'price' => 30], ['product' => 'Door', 'price' => 100], ]); $filtered = $collection->whereNotBetween('price', [100, 200]); $filtered->all(); / [ ['product' => 'Chair', 'price' => 80], ['product' => 'Pencil', 'price' => 30], ] /

whereNotIn()

whereNotInメソッドは、指定されたアイテムの値が指定された配列に含まれている要素をコレクションから削除します。 $collection = collect([ ['product' => 'Desk', 'price' => 200], ['product' => 'Chair', 'price' => 100], ['product' => 'Bookcase', 'price' => 150], ['product' => 'Door', 'price' => 100], ]); $filtered = $collection->whereNotIn('price', [150, 200]); $filtered->all(); / [ ['product' => 'Chair', 'price' => 100], ['product' => 'Door', 'price' => 100], ] / whereNotInメソッドは、アイテムの値をチェックする際に「緩い」比較を使用します。つまり、整数値を持つ文字列は、同じ値の整数と等しいとみなされます。「厳密な」比較を使用してフィルタリングするには、whereNotInStrictメソッドを使用してください。

whereNotInStrict()

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

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

whereNotNull()

whereNotNullメソッドは、指定されたキーがnullでないコレクションのアイテムを返します。

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

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

$filtered->all();

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

whereNull()

whereNullメソッドは、指定されたキーがnullであるコレクションのアイテムを返します。

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

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

$filtered->all();

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

wrap()

静的なwrapメソッドは、指定された値をコレクションに適用可能な場合にその値をコレクションでラップします。

use Illuminate\Support\Collection;

$collection = Collection::wrap('John Doe');

$collection->all();

// ['John Doe']

$collection = Collection::wrap(['John Doe']);

$collection->all();

// ['John Doe']

$collection = Collection::wrap(collect('John Doe'));

$collection->all();

// ['John Doe']

zip()

zipメソッドは、指定された配列の値を元のコレクションの値と対応するインデックスでマージします。

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

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

$zipped->all();

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

高階メッセージ

コレクションは、"高階メッセージ"のサポートも提供します。これは、コレクション上で一般的なアクションを実行するためのショートカットです。高階メッセージを提供するコレクションメソッドは以下の通りです：average、avg、contains、each、every、filter、first、flatMap、groupBy、keyBy、map、max、min、partition、reject、skipUntil、skipWhile、some、sortBy、sortByDesc、sum、takeUntil、takeWhile、およびunique。

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

use App\Models\User;

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

$users->each->markAsVip();

同様に、sum高階メッセージを使用して、ユーザーコレクションの"votes"の合計数を集計することができます。

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

return $users->sum->votes;

遅延コレクション

はじめに

Warning

Laravelの遅延コレクションについて学ぶ前に、PHPのジェネレータについて理解する時間を取ってください。

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

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

use App\Models\LogEntry;
use Illuminate\Support\LazyCollection;

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

    while (($line = fgets($handle)) !== false) {
        yield $line;
    }
})->chunk(4)->map(function (array $lines) {
    return LogEntry::fromLines($lines);
})->each(function (LogEntry $logEntry) {
    // ログエントリを処理する...
});

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

use App\Models\User;

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

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

use App\Models\User;

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

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

遅延コレクションの作成

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

use Illuminate\Support\LazyCollection;

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

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

Enumerable契約

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

all average avg chunk chunkWhile collapse collect combine concat contains containsStrict count countBy crossJoin dd diff diffAssoc diffKeys dump duplicates duplicatesStrict each eachSpread every except filter first firstOrFail firstWhere flatMap flatten flip forPage get groupBy has implode intersect intersectAssoc intersectByKeys isEmpty isNotEmpty join keyBy keys last macro make map mapInto mapSpread mapToGroups mapWithKeys max median merge mergeRecursive min mode nth only pad partition pipe pluck random reduce reject replace replaceRecursive reverse search shuffle skip slice sole some sort sortBy sortByDesc sortKeys sortKeysDesc split sum take tap times toArray toJson union unique uniqueStrict unless unlessEmpty unlessNotEmpty unwrap values when whenEmpty whenNotEmpty where whereStrict whereBetween whereIn whereInStrict whereInstanceOf whereNotBetween whereNotIn whereNotInStrict wrap zip

Warning

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

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

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

takeUntilTimeout()

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

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

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

    sleep(1);
});

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

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

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

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

tapEach()

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

// まだ何もダンプされていません...
$lazyCollection = LazyCollection::times(INF)->tapEach(function (int $value) {
    dump($value);
});

// 3つのアイテムがダンプされます...
$array = $lazyCollection->take(3)->all();

// 1
// 2
// 3

throttle()

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

use App\Models\User;

User::where('vip', true)
    ->cursor()
    ->throttle(seconds: 1)
    ->each(function (User $user) {
        // 外部APIを呼び出す...
    });

remember()

rememberメソッドは、すでに列挙された値を記憶し、以降のコレクション列挙時にそれらを再取得しない新しい遅延コレクションを返します。

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

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

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

ユーザーノート

+ ユーザーノートを表示する

ユーザーノートについて

PHPマニュアルのように、マニュアルを補足する情報の共有を目的としてます。

• 掲示板ではありません。議論、質問、別のノートへの返信はできません。
• バグや改善要望、または翻訳の Issue は、該当する GitHub リポジトリで報告してください。
• ノートは事前の通知なく削除される場合があります。
• Giscussのコメントシステムを流用しています。そのためノートとしては最適化されてないことをご了承ください。
• 保証されていません。投稿したノートが消失する事やノート機能全体が閉鎖する可能性があります。
• お願い：いいノートにはup voteを、この規約に違反しているノートを見つけた場合は、優しくdown voteしてください。