集合 (Collections)

簡介 (Introduction)

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 實例。

建立集合 (Creating Collections)

如上所述，collect 輔助函式會為給定的陣列返回一個新的 Illuminate\Support\Collection 實例。因此，建立一個集合非常簡單：

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

你也可以使用 make 和 fromJson 方法來建立集合。

[!NOTE] > Eloquent 查詢的結果總是作為 Collection 實例返回。

擴充集合 (Extending Collections)

集合是「可巨集化 (macroable)」的，這允許你在執行時向 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 方法中宣告集合巨集。

巨集參數 (Macro Arguments)

如果需要，你可以定義接受額外參數的巨集：

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

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

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

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

可用方法 (Available Methods)

可用方法 (Available Methods)

對於剩餘的大部分集合文件，我們將討論 Collection 類別上可用的每個方法。請記住，所有這些方法都可以鏈式呼叫，以流暢地操作底層陣列。此外，幾乎每個方法都返回一個新的 Collection 實例，允許你在必要時保留集合的原始副本：

方法列表 (Method Listing)

after()

The after method returns the item after the given item. null is returned if the given item is not found or is the last item:

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

$collection->after(3);

// 4

$collection->after(5);

// null

This method searches for the given item using "loose" comparison, meaning a string containing an integer value will be considered equal to an integer of the same value. To use "strict" comparison, you may provide the strict argument to the method:

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

// null

Alternatively, you may provide your own closure to search for the first item that passes a given truth test:

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 className="row">
        @foreach ($chunk as $product)
            <div className="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]

collapseWithKeys()

collapseWithKeys 方法將陣列或集合的集合扁平化為單個集合，並保持原始鍵不變。如果集合已經是扁平的，它將返回一個空集合：

$collection = collect([
    ['first'  => collect([1, 2, 3])],
    ['second' => [4, 5, 6]],
    ['third'  => collect([7, 8, 9])]
]);

$collapsed = $collection->collapseWithKeys();

$collapsed->all();

// [
//     'first'  => [1, 2, 3],
//     'second' => [4, 5, 6],
//     'third'  => [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] 當你有一個 Enumerable 實例並需要一個非惰性集合實例時，collect 方法特別有用。由於 collect() 是 Enumerable 合約的一部分，你可以安全地使用它來獲取 Collection 實例。

combine()

combine 方法將集合的值作為鍵，與另一個陣列或集合的值結合：

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

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

$combined->all();

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

concat()

concat 方法將給定的陣列或集合的值附加到另一個集合的末尾：

$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

collect([1, 2, 3])->containsOneItem(fn (int $item) => $item === 2);

// true

containsStrict()

此方法與 contains 方法具有相同的簽名；但是，所有值都使用「嚴格」比較進行比較。

[!NOTE] 當使用 Eloquent Collections 時，此方法的行為會被修改。

count()

count 方法返回集合中的項目總數：

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

$collection->count();

// 4

countBy()

countBy 方法計算集合中值的出現次數。預設情況下，該方法計算每個元素的出現次數，允許你計算集合中某些「類型」的元素：

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

$counted = $collection->countBy();

$counted->all();

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

你可以傳遞一個閉包給 countBy 方法，以透過自訂值計算所有項目：

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

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

$counted->all();

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

crossJoin()

crossJoin 方法將集合的值與給定的陣列或集合進行交叉連接，返回包含所有可能排列的笛卡兒積：

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

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

$matrix->all();

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

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

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

$matrix->all();

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

dd()

dd 方法傾印集合的項目並結束腳本的執行：

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

$collection->dd();

/*
    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 Collections 時，此方法的行為會被修改。

diffAssoc()

diffAssoc 方法根據鍵和值將集合與另一個集合或純 PHP array 進行比較。此方法將返回原始集合中存在但給定集合中不存在的鍵 / 值對：

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

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

$diff->all();

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

diffAssocUsing()

與 diffAssoc 不同，diffAssocUsing 接受使用者提供的回呼函數進行索引比較：

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

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

$diff->all();

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

回呼必須是一個比較函數，返回小於、等於或大於零的整數。有關更多資訊，請參閱 PHP 文件中的 array_diff_uassoc，這是 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]);

```php
$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 方法在檢查項目值時使用「寬鬆」比較，這意味著包含整數值的字串將被視為等於相同值的整數。

doesntContainStrict()

此方法與 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();

/*
    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 方法。在這種情況下，firstWhere 方法將返回給定項目鍵的值為「truthy」的第一個項目：

$collection->firstWhere('age');

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

flatMap()

flatMap 方法遍歷集合並將每個值傳遞給給定的閉包。閉包可以自由修改項目並返回它，從而形成一個修改後項目的新集合。然後，陣列被扁平化一層：

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

// []

[!WARNING] 與大多數其他集合方法不同，forget 不返回新的修改後的集合；它修改並返回被呼叫的集合。

forPage()

forPage 方法返回一個包含給定頁碼上項目的新集合。該方法接受頁碼作為第一個參數，每頁顯示的項目數作為第二個參數：

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

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

$chunk->all();

// [4, 5, 6]

fromJson()

靜態 fromJson 方法透過使用 json_decode PHP 函數解碼給定的 JSON 字串來建立一個新的集合實例：

use Illuminate\Support\Collection;

$json = json_encode([
    'name' => 'Taylor Otwell',
    'role' => 'Developer',
    'status' => 'Active',
]);

$collection = Collection::fromJson($json);

get()

get 方法返回給定鍵的項目。如果鍵不存在，則返回 null：

$collection = collect(['name' => 'Taylor', 'framework' => 'Laravel']);

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

// Taylor

你可以選擇傳遞預設值作為第二個參數：

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

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

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

hasAny 方法判斷集合中是否存在任何給定的鍵：

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

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

// true

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

// false

implode()

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

intersect 方法從原始集合中移除任何不存在於給定陣列或集合中的值。生成的集合將保留原始集合的鍵：

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

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

$intersect->all();

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

[!NOTE] 當使用 Eloquent Collections 時，此方法的行為會被修改。

intersectUsing()

intersectUsing()

intersectUsing 方法從原始集合中移除任何不存在於給定陣列或集合中的值，使用自訂回呼來比較值。生成的集合將保留原始集合的鍵：

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

$intersect = $collection->intersectUsing(['desk', 'chair', 'bookcase'], function (string $a, string $b) {
    return strcasecmp($a, $b);
});

$intersect->all();

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

intersectAssoc()

intersectAssoc()

intersectAssoc 方法將原始集合與另一個集合或陣列進行比較，返回在所有給定集合中都存在的鍵 / 值對：

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

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

$intersect->all();

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

intersectAssocUsing()

intersectAssocUsing()

intersectAssocUsing 方法將原始集合與另一個集合或陣列進行比較，返回兩者中都存在的鍵 / 值對，使用自訂比較回呼來確定鍵和值的相等性：

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

$intersect = $collection->intersectAssocUsing([
    'color' => 'blue',
    'size' => 'M',
    'material' => 'polyester',
], function (string $a, string $b) {
    return strcasecmp($a, $b);
});

$intersect->all();

// ['Size' => 'M']

intersectByKeys()

intersectByKeys()

intersectByKeys 方法從原始集合中移除任何鍵及其對應值，如果這些鍵不存在於給定陣列或集合中：

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

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

$intersect->all();

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

isEmpty()

isEmpty()

如果集合為空，isEmpty 方法返回 true；否則返回 false：

collect([])->isEmpty();

// true

isNotEmpty()

如果集合不為空，isNotEmpty 方法返回 true；否則返回 false：

collect([])->isNotEmpty();

// false

join()

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

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

keys 方法返回集合的所有鍵：

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

$keys = $collection->keys();

$keys->all();

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

last()

last()

last 方法返回集合中最後一個通過給定真值測試的元素：

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

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

靜態 macro 方法允許你在執行時向 Collection 類別新增方法。有關更多資訊，請參閱 擴充集合 文件。

make()

make()

靜態 make 方法建立一個新的集合實例。請參閱 建立集合 部分。

use Illuminate\Support\Collection;

$collection = Collection::make([1, 2, 3]);

map()

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

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

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

mapToGroups 方法根據給定的閉包對集合的項目進行分組。閉包應返回包含單個鍵 / 值對的關聯陣列，從而形成一個分組值的新集合：

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

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

$grouped->all();

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

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

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

mapWithKeys()

mapWithKeys 方法遍歷集合並將每個值傳遞給給定的回呼。回呼應返回包含單個鍵 / 值對的關聯陣列：

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

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

$keyed->all();

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

max()

max 方法返回給定鍵的最大值：

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

// 20

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

// 5

median()

median 方法返回給定鍵的 中位數：

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

// 15

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

// 1.5

merge()

merge 方法將給定的陣列或集合與原始集合合併。如果給定項目中的字串鍵與原始集合中的字串鍵匹配，則給定項目的值將覆蓋原始集合中的值：

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

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

$merged->all();

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

如果給定項目的鍵是數字，則值將附加到集合的末尾：

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

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

$merged->all();

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

mergeRecursive()

mergeRecursive 方法將給定的陣列或集合遞歸地與原始集合合併。如果給定項目中的字串鍵與原始集合中的字串鍵匹配，則這些鍵的值將合併到一個陣列中，並且這是遞歸完成的：

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

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

$merged->all();

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

min()

min 方法返回給定鍵的最小值：

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

// 10

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

// 1

mode()

mode 方法返回給定鍵的 眾數：

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

// [10]

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

// [1]

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

// [1, 2]

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

你可以選擇傳遞一個起始偏移量作為第二個參數：

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

[!NOTE] 當與 Eloquent collections 互動時，此方法的行為會被修改。

percentage()

percentage 方法可用於快速確定集合中通過給定真值測試的項目的百分比：

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

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

// 33.33

預設情況下，百分比將四捨五入到小數點後兩位。但是，你可以透過向該方法提供第二個參數來自訂此行為：

$percentage = $collection->percentage(fn (int $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']]

If duplicate keys exist, the last matching element will be inserted into the plucked collection:

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

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

$plucked->all();

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

pop()

pop 方法移除並返回集合中的最後一個項目。如果集合為空，將返回 null：

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

$collection->pop();

// 5

$collection->all();

// [1, 2, 3, 4]

你可以傳遞一個整數給 pop 方法，以從集合末尾移除並返回多個項目：

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

$collection->pop(3);

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

$collection->all();

// [1, 2]

prepend()

prepend 方法將一個項目新增到集合的開頭：

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

$collection->prepend(0);

$collection->all();

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

你也可以傳遞第二個參數來指定前置項目的鍵：

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

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

$collection->all();

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

pull()

pull 方法透過鍵從集合中移除並返回一個項目：

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

$collection->pull('name');

// 'Desk'

$collection->all();

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

push()

push 方法將一個項目附加到集合的末尾：

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

$collection->push(5);

$collection->all();

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

你也可以提供多個項目來附加到集合的末尾：

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

$collection->push(5, 6, 7);

$collection->all();

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

put()

put 方法在集合中設定給定的鍵和值：

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

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

$collection->all();

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

random()

random 方法從集合中返回一個隨機項目：

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

$collection->random();

// 4 - (retrieved randomly)

你可以傳遞一個整數給 random 以指定你希望隨機檢索多少個項目。當明確傳遞你希望接收的項目數量時，總是返回一個項目集合：

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

$random->all();

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

如果集合實例的項目少於請求的數量，random 方法將拋出 InvalidArgumentException。

random 方法也接受一個閉包，該閉包將接收當前的集合實例：

use Illuminate\Support\Collection;

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

$random->all();

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

range()

range 方法返回包含指定範圍內整數的集合：

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

$collection->all();

// [3, 4, 5, 6]

reduce()

reduce 方法將集合減少為單個值，將每次迭代的結果傳遞給下一次迭代：

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

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

// 6

第一次迭代時 $carry 的值為 null；但是，你可以透過傳遞第二個參數給 reduce 來指定其初始值：

$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, string $key) use ($ratio) {
    return $carry + ($value * $ratio[$key]);
}, 0);

// 4264

reduceSpread()

reduceSpread 方法將集合減少為一個值陣列，將每次迭代的結果傳遞給下一次迭代。此方法類似於 reduce 方法；但是，它可以接受多個初始值：

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

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

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

reject()

reject 方法使用給定的閉包過濾集合。如果項目應該從結果集合中移除，閉包應返回 true：

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

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

$filtered->all();

// [1, 2]

關於 reject 方法的反向操作，請參閱 filter 方法。

replace()

replace 方法的行為類似於 merge；但是，除了覆蓋具有字串鍵的匹配項目外，replace 方法還將覆蓋集合中具有匹配數字鍵的項目：

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

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

$replaced->all();

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

replaceRecursive()

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] - (generated randomly)

skip()

skip 方法返回一個新集合，其中從集合開頭移除了給定數量的元素：

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

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

$collection->all();

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

skipUntil()

skipUntil 方法跳過集合中的項目，直到給定的回呼返回 true。一旦回呼返回 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 方法跳過集合中的項目，直到給定的回呼返回 false。一旦回呼返回 false，集合中的所有剩餘項目將作為一個新集合返回：

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

```php
$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 方法返回集合中第一個通過給定真值測試的元素，但前提是真值測試只匹配一個元素：

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

// 2

你也可以傳遞一個鍵 / 值對給 sole 方法，這將返回集合中第一個匹配給定對的元素，但前提是只有一個元素匹配：

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

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

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

或者，如果集合中只有一個元素，你也可以不帶參數呼叫 sole 方法來獲取該元素：

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

$collection->sole();

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