コレクション

• 導入
  • コレクションの作成
  • コレクションの拡張
• 利用可能なメソッド
• 高階メッセージ
• 遅延コレクション
  • 導入
  • 遅延コレクションの作成
  • 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]);

コレクションの拡張

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

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

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

マクロ引数

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

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

利用可能なメソッド

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

メソッドリスト

after()

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]

combine()

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

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

concat()

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

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

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

contains()

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

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

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

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

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

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

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

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

containsOneItem()

containsOneItemメソッドは、コレクションに単一の項目が含まれているかどうかを判断します。

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

containsStrict()

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

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(['[email protected]', '[email protected]', '[email protected]']);
 
$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]

diffAssoc()

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

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

diffAssocUsing()

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

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

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

diffKeys()

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

$collection = collect([
    'one' => 10,
    'two' => 20,
    'three' => 30,
    'four' => 40,
    'five' => 50,
]);
 
$diff = $collection->diffKeys([
    'two' => 2,
    'four' => 4,
    'six' => 6,
    'eight' => 8,
]);
 
$diff->all();
 
// ['one' => 10, 'three' => 30, 'five' => 50]

doesntContain()

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

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

または、文字列をdoesntContainメソッドに渡して、コレクションに指定された項目値が含まれていないかどうかを判断できます。

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

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

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

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

dot()

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

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

dump()

dumpメソッドは、コレクションの項目をダンプします。

$collection = collect(['John Doe', 'Jane Doe']);
 
$collection->dump();
 
/*
    Collection {
        #items: array:2 [
            0 => "John Doe"
            1 => "Jane Doe"
        ]
    }
*/

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

duplicates()

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

$collection = collect(['a', 'b', 'a', 'c', 'b']);
 
$collection->duplicates();
 
// [2 => 'a', 4 => 'b']

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

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

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

filter()

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

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

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

$collection = collect([1, 2, 3, null, false, '', 0, []]);
 
$collection->filter()->all();
 
// [1, 2, 3]

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

first()

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

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

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

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

firstOrFail()

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

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

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

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

firstWhere()

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

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

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

$collection->firstWhere('age', '>=', 18);
 
// ['name' => 'Diego', 'age' => 23]

whereメソッドと同様に、firstWhereメソッドに1つの引数を渡すことができます。このシナリオでは、firstWhereメソッドは、指定された項目キーの値が「真」である最初の項目を返します。

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

flatMap()

flatMapメソッドは、コレクションを反復処理し、各値を指定されたクロージャに渡します。クロージャは、項目を自由に変更して返すことができるため、変更された項目の新しいコレクションが形成されます。次に、配列は1つのレベルで平坦化されます。

$collection = collect([
    ['name' => 'Sally'],
    ['school' => 'Arkansas'],
    ['age' => 28]
]);
 
$flattened = $collection->flatMap(function (array $values) {
    return array_map('strtoupper', $values);
});
 
$flattened->all();
 
// ['name' => 'SALLY', 'school' => 'ARKANSAS', 'age' => '28'];

flatten()

flattenメソッドは、多次元コレクションを単次元にフラット化します。

$collection = collect([
    'name' => 'taylor',
    'languages' => [
        'php', 'javascript'
    ]
]);
 
$flattened = $collection->flatten();
 
$flattened->all();
 
// ['taylor', 'php', 'javascript'];

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

$collection = collect([
    'Apple' => [
        [
            'name' => 'iPhone 6S',
            'brand' => 'Apple'
        ],
    ],
    'Samsung' => [
        [
            'name' => 'Galaxy S7',
            'brand' => 'Samsung'
        ],
    ],
]);
 
$products = $collection->flatten(1);
 
$products->values()->all();
 
/*
    [
        ['name' => 'iPhone 6S', 'brand' => 'Apple'],
        ['name' => 'Galaxy S7', 'brand' => 'Samsung'],
    ]
*/

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

flip()

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

$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
 
$flipped = $collection->flip();
 
$flipped->all();
 
// ['taylor' => 'name', 'laravel' => 'framework']

forget()

forget メソッドは、コレクションからキーで指定された項目を削除します。

$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
 
// Forget a single key...
$collection->forget('name');
 
// ['framework' => 'laravel']
 
// Forget multiple keys...
$collection->forget(['name', 'framework']);
 
// []

forPage()

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

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

get()

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 '[email protected]';
});
 
// [email protected]

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

intersectAssoc()

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

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

intersectByKeys()

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

$collection = collect([
    'serial' => 'UX301', 'type' => 'screen', 'year' => 2009,
]);
 
$intersect = $collection->intersectByKeys([
    'reference' => 'UX404', 'type' => 'tab', 'year' => 2011,
]);
 
$intersect->all();
 
// ['type' => 'screen', 'year' => 2009]

isEmpty()

isEmpty メソッドは、コレクションが空の場合 true を返し、それ以外の場合は false を返します。

collect([])->isEmpty();
 
// true

isNotEmpty()

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

collect([])->isNotEmpty();
 
// false

join()

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

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

keyBy()

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

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

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

$keyed = $collection->keyBy(function (array $item, int $key) {
    return strtoupper($item['product_id']);
});
 
$keyed->all();
 
/*
    [
        'PROD-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
        'PROD-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
    ]
*/

keys()

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

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

last()

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

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

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

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

lazy()

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

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

これは、多数の項目を含む巨大な Collection に対して変換を実行する必要がある場合に特に役立ちます。

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

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

macro()

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

make()

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

map()

map メソッドは、コレクションを反復処理し、各値を指定されたコールバックに渡します。コールバックは、項目を自由に修正して返すことができ、これにより、修正された項目の新しいコレクションが形成されます。

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

mapInto()

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

class Currency
{
    /**
     * Create a new currency instance.
     */
    function __construct(
        public string $code,
    ) {}
}
 
$collection = collect(['USD', 'EUR', 'GBP']);
 
$currencies = $collection->mapInto(Currency::class);
 
$currencies->all();
 
// [Currency('USD'), Currency('EUR'), Currency('GBP')]

mapSpread()

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

$collection = collect([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
 
$chunks = $collection->chunk(2);
 
$sequence = $chunks->mapSpread(function (int $even, int $odd) {
    return $even + $odd;
});
 
$sequence->all();
 
// [1, 5, 9, 13, 17]

mapToGroups()

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

$collection = collect([
    [
        'name' => 'John Doe',
        'department' => 'Sales',
    ],
    [
        'name' => 'Jane Doe',
        'department' => 'Sales',
    ],
    [
        'name' => 'Johnny Doe',
        'department' => 'Marketing',
    ]
]);
 
$grouped = $collection->mapToGroups(function (array $item, int $key) {
    return [$item['department'] => $item['name']];
});
 
$grouped->all();
 
/*
    [
        'Sales' => ['John Doe', 'Jane Doe'],
        'Marketing' => ['Johnny Doe'],
    ]
*/
 
$grouped->get('Sales')->all();
 
// ['John Doe', 'Jane Doe']

mapWithKeys()

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

$collection = collect([
    [
        'name' => 'John',
        'department' => 'Sales',
        'email' => '[email protected]',
    ],
    [
        'name' => 'Jane',
        'department' => 'Marketing',
        'email' => '[email protected]',
    ]
]);
 
$keyed = $collection->mapWithKeys(function (array $item, int $key) {
    return [$item['email'] => $item['name']];
});
 
$keyed->all();
 
/*
    [
        '[email protected]' => 'John',
        '[email protected]' => 'Jane',
    ]
*/

max()

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

$max = collect([
    ['foo' => 10],
    ['foo' => 20]
])->max('foo');
 
// 20
 
$max = collect([1, 2, 3, 4, 5])->max();
 
// 5

median()

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

$median = collect([
    ['foo' => 10],
    ['foo' => 10],
    ['foo' => 20],
    ['foo' => 40]
])->median('foo');
 
// 15
 
$median = collect([1, 1, 2, 4])->median();
 
// 1.5

merge()

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

$collection = collect(['product_id' => 1, 'price' => 100]);
 
$merged = $collection->merge(['price' => 200, 'discount' => false]);
 
$merged->all();
 
// ['product_id' => 1, 'price' => 200, 'discount' => false]

指定された項目のキーが数値の場合、値はコレクションの最後に追加されます。

$collection = collect(['Desk', 'Chair']);
 
$merged = $collection->merge(['Bookcase', 'Door']);
 
$merged->all();
 
// ['Desk', 'Chair', 'Bookcase', 'Door']

mergeRecursive()

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

$collection = collect(['product_id' => 1, 'price' => 100]);
 
$merged = $collection->mergeRecursive([
    'product_id' => 2,
    'price' => 200,
    'discount' => false
]);
 
$merged->all();
 
// ['product_id' => [1, 2], 'price' => [100, 200], 'discount' => false]

min()

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

$min = collect([['foo' => 10], ['foo' => 20]])->min('foo');
 
// 10
 
$min = collect([1, 2, 3, 4, 5])->min();
 
// 1

mode()

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

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

multiply()

multiply メソッドは、コレクション内のすべての項目の指定された数のコピーを作成します。

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

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

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