Collections

簡介
- 建立集合
- 擴充集合
可用方法
高階訊息
惰性集合

簡介

Illuminate\Support\Collection 類別提供了一個流暢且方便的包裝器，用於處理資料陣列。例如，請看以下程式碼。我們將使用 collect 輔助函數從陣列建立一個新的 Collection 實例，對每個元素執行 strtoupper 函數，然後移除所有空元素：

php

$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 實例。因此，建立一個集合就如同以下範例一樣簡單：

php

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

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

📌 備註

Eloquent 查詢的結果總是會作為 Collection 實例傳回。

擴充集合

集合是「可巨集化 (macroable)」的，這表示您可以在執行階段為 Collection 類別新增額外的方法。Illuminate\Support\Collection 類別的 macro 方法接受一個閉包，該閉包將在您的 Macro 被呼叫時執行。Macro 閉包可以透過 $this 存取集合的其他方法，就像它是集合類別的實際方法一樣。例如，以下程式碼為 Collection 類別新增了一個 toUpper 方法：

php

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。

Macro 引數

如有必要，您可以定義接受額外引數的 Macro：

php

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 collapseWithKeys collect combine concat contains containsOneItem containsStrict count countBy crossJoin dd diff diffAssoc diffAssocUsing diffKeys doesntContain doesntContainStrict dot dump duplicates duplicatesStrict each eachSpread ensure every except filter first firstOrFail firstWhere flatMap flatten flip forget forPage fromJson get groupBy has hasAny implode intersect intersectUsing intersectAssoc intersectAssocUsing 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 toPrettyJson 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：

php

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

$collection->after(3);

// 4

$collection->after(5);

// null

此方法使用「鬆散」比對來搜尋指定項目，這表示包含整數值的字串將被視為與具有相同值的整數相等。若要使用「嚴格」比對，您可以將 strict 引數提供給該方法：

php

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

// null

或者，您可以提供自己的閉包來搜尋通過指定真值測試的第一個項目：

php

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

// 8

`all()`

all 方法會回傳集合底層的陣列：

php

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

// [1, 2, 3]

`average()`

avg 方法的別名。

`avg()`

avg 方法會回傳指定鍵的平均值：

php

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

php

$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 方法會將集合分割成多個指定大小的較小集合：

php

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

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

$chunks->all();

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

當在 views 中使用 Bootstrap 等網格系統時，此方法特別有用。例如，想像您有一個 Eloquent 模型的集合，您想在網格中顯示它們：

blade

@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 變數可用於檢查前一個元素：

php

$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 方法會將陣列或集合的集合折疊成單一的扁平化集合：

php

$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 方法會將陣列或集合的集合扁平化為單一集合，並保留原始鍵。如果集合已經扁平化，它將回傳一個空集合：

php

$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 實例，其中包含集合中目前的項目：

php

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

$collectionB = $collectionA->collect();

$collectionB->all();

// [1, 2, 3]

collect 方法主要用於將 lazy collections 轉換為標準的 Collection 實例：

php

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

$collection = $lazyCollection->collect();

$collection::class;

// 'Illuminate\Support\Collection'

$collection->all();

// [1, 2, 3]

📌 備註

當您有一個 Enumerable 實例並需要一個非惰性 (non-lazy) 的 Collection 實例時，collect 方法特別有用。由於 collect() 是 Enumerable 契約的一部分，您可以安全地使用它來取得 Collection 實例。

`combine()`

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

php

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

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

$combined->all();

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

`concat()`

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

php

$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 方法，以判斷集合中是否存在符合指定真值測試的元素：

php

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

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

// false

或者，您可以將字串傳遞給 contains 方法，以判斷集合是否包含指定項目值：

php

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

$collection->contains('Desk');

// true

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

// false

您也可以將鍵/值對傳遞給 contains 方法，這將判斷集合中是否存在給定的鍵/值對：

php

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

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

// false

contains 方法在檢查項目值時使用「鬆散」比對，這表示包含整數值的字串將被視為與具有相同值的整數相等。若要使用「嚴格」比對進行篩選，請使用 containsStrict 方法。

對於 contains 的反向操作，請參閱 doesntContain 方法。

`containsOneItem()`

containsOneItem 方法會判斷集合是否包含單一項目：

php

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 方法具有相同的簽章；然而，所有值都將使用「嚴格」比較。

📌 備註

使用 Eloquent Collections 時，此方法的行為會有所不同。

`count()`

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

php

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

$collection->count();

// 4

`countBy()`

countBy 方法計算集合中值的出現次數。預設情況下，此方法會計算每個元素的出現次數，讓您可以計算集合中某些「類型」元素的數量：

php

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

$counted = $collection->countBy();

$counted->all();

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

您可以傳遞一個閉包給 countBy 方法，以根據自訂值計算所有項目：

php

$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 方法將集合中的值與給定的陣列或集合進行交叉合併，回傳一個包含所有可能排列的笛卡爾積：

php

$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 方法傾印集合中的項目並終止腳本執行：

php

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

$collection->dd();

/*
    array:2 [
        0 => "John Doe"
        1 => "Jane Doe"
    ]
*/

如果您不想停止腳本執行，請改用 dump 方法。

`diff()`

diff 方法根據其值將集合與另一個集合或純 PHP array 進行比較。此方法將回傳原始集合中不存在於給定集合中的值：

php

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

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

$diff->all();

// [1, 3, 5]

📌 備註

使用 Eloquent Collections 時，此方法的行為會有所不同。

`diffAssoc()`

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

php

$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 接受一個使用者提供的回呼函式用於索引比較：

php

$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 進行比較。此方法將回傳原始集合中不存在於給定集合中的鍵/值對：

php

$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 方法，以判斷集合中是否存在與給定真值測試不符合的元素：

php

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

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

// false

或者，您可以傳遞一個字串給 doesntContain 方法，以判斷集合是否不包含給定項目值：

php

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

$collection->doesntContain('Table');

// true

$collection->doesntContain('Desk');

// false

您還可以傳遞一個鍵/值對給 doesntContain 方法，以判斷給定的鍵/值對是否不存在於集合中：

php

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

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

// true

doesntContain 方法在檢查項目值時使用「寬鬆」比較，這表示包含整數值的字串將被視為與具有相同值的整數相等。

`doesntContainStrict()`

此方法與 doesntContain 方法具有相同的簽章；然而，所有值都將使用「嚴格」比較。

`dot()`

dot 方法將多維集合扁平化為一個使用「點」符號表示深度的單層集合：

php

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

$flattened = $collection->dot();

$flattened->all();

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

`dump()`

dump 方法傾印集合中的項目：

php

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

$collection->dump();

/*
    array:2 [
        0 => "John Doe"
        1 => "Jane Doe"
    ]
*/

如果您想在傾印集合後停止腳本執行，請改用 dd 方法。

`duplicates()`

duplicates 方法從集合中檢索並回傳重複的值：

php

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

$collection->duplicates();

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

如果集合包含陣列或物件，您可以傳遞您希望檢查重複值的屬性鍵：

php

$employees = collect([
    ['email' => '[email protected]', 'position' => 'Developer'],
    ['email' => '[email protected]', 'position' => 'Designer'],
    ['email' => '[email protected]', 'position' => 'Developer'],
]);

$employees->duplicates('position');

// [2 => 'Developer']

`duplicatesStrict()`

此方法與 duplicates 方法具有相同的簽名；然而，所有值都使用「嚴格 (strict)」比較來進行比較。

`each()`

each 方法會迭代集合中的項目，並將每個項目傳遞給一個閉包 (closure)：

php

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

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

如果您想停止迭代項目，您可以從閉包中返回 false：

php

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

`eachSpread()`

eachSpread 方法會迭代集合中的項目，將每個巢狀項目值傳遞給指定的回呼 (callback)：

php

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

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

您可以透過從回呼中返回 false 來停止迭代項目：

php

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

`ensure()`

ensure 方法可用於驗證集合中的所有元素是否為給定類型或類型列表。否則，將拋出 UnexpectedValueException 異常：

php

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

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

也可以指定原始類型，例如 string、int、float、bool 和 array：

php

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

⚠️ 警告

ensure 方法不保證之後不會向集合中添加不同類型的元素。

`every()`

every 方法可用於驗證集合中的所有元素是否通過給定的真實性測試：

php

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

// false

如果集合為空，every 方法將返回 true：

php

$collection = collect([]);

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

// true

`except()`

except 方法會返回集合中除指定鍵以外的所有項目：

php

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

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

$filtered->all();

// ['product_id' => 1]

若要執行 except 的反向操作，請參閱 only 方法。

📌 備註

使用 Eloquent Collections 時，此方法的行為會被修改。

`filter()`

filter 方法會使用指定的回呼過濾集合，只保留通過給定真實性測試的項目：

php

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

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

$filtered->all();

// [3, 4]

如果未提供回呼，則集合中所有等同於 false 的條目都將被移除：

php

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

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

// [1, 2, 3]

若要執行 filter 的反向操作，請參閱 reject 方法。

`first()`

first 方法會返回集合中第一個通過指定真實性測試的元素：

php

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

// 3

您也可以不帶任何參數呼叫 first 方法以獲取集合中的第一個元素。如果集合為空，則返回 null：

php

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

// 1

`firstOrFail()`

firstOrFail 方法與 first 方法相同；但是，如果沒有找到結果，將拋出 Illuminate\Support\ItemNotFoundException 異常：

php

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

// Throws ItemNotFoundException...

您也可以不帶任何參數呼叫 firstOrFail 方法以獲取集合中的第一個元素。如果集合為空，將拋出 Illuminate\Support\ItemNotFoundException 異常：

php

collect([])->firstOrFail();

// Throws ItemNotFoundException...

`firstWhere()`

firstWhere 方法會返回集合中具有指定鍵值對的第一個元素：

php

$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 方法：

php

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

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

與 where 方法類似，您可以向 firstWhere 方法傳遞一個參數。在此情境中，firstWhere 方法將返回第一個其給定項目鍵值為「真值 (truthy)」的項目：

php

$collection->firstWhere('age');

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

`flatMap()`

flatMap 方法會迭代集合中的每個值並將其傳遞給指定的閉包 (closure)。閉包可以自由修改項目並返回它，從而形成一個新的修改過的項目集合。然後，該陣列會被扁平化一個層級：

php

$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 方法會將多維集合扁平化為單一維度：

php

$collection = collect([
    'name' => 'Taylor',
    'languages' => [
        'PHP', 'JavaScript'
    ]
]);

$flattened = $collection->flatten();

$flattened->all();

// ['Taylor', 'PHP', 'JavaScript'];

如有需要，您可以向 flatten 方法傳遞一個「深度 (depth)」參數：

php

$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 方法會將集合的鍵與其對應的值互換：

php

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

$flipped = $collection->flip();

$flipped->all();

// ['Taylor' => 'name', 'Laravel' => 'framework']

`forget()`

forget 方法依據其鍵從集合中移除項目：

php

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

// Forget a single key...
$collection->forget('name');

// ['framework' => 'Laravel']

// Forget multiple keys...
$collection->forget(['name', 'framework']);

// []

⚠️ 警告

與大多數其他 Collection 方法不同，forget 並不回傳一個新的已修改集合；它會修改並回傳被呼叫的集合本身。

`forPage()`

forPage 方法會回傳一個新的集合，其中包含指定頁碼上會出現的項目。該方法接受頁碼作為第一個引數，並接受每頁顯示的項目數量作為第二個引數：

php

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

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

$chunk->all();

// [4, 5, 6]

`fromJson()`

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

php

use Illuminate\Support\Collection;

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

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

`get()`

get 方法會回傳指定鍵的項目。如果鍵不存在，則回傳 null：

php

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

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

// Taylor

您可以選擇性地傳入一個預設值作為第二個引數：

php

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

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

// 34

您甚至可以傳入一個回呼函式作為方法的預設值。如果指定的鍵不存在，則會回傳該回呼函式的結果：

php

$collection->get('email', function () {
    return '[email protected]';
});

// [email protected]

`groupBy()`

groupBy 方法會依據給定的鍵來分組集合中的項目：

php

$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 外，您也可以傳入一個回呼函式。該回呼函式應該回傳您希望用來分組的鍵值：

php

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

多個分組條件可以作為一個陣列傳入。每個陣列元素將應用於多維陣列中的對應層級：

php

$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 方法會判斷給定的鍵是否存在於集合中：

php

$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 方法會判斷給定的任一個鍵是否存在於集合中：

php

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

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

// true

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

// false

`implode()`

implode 方法將集合中的項目連接起來。它的引數取決於集合中項目的類型。如果集合包含陣列或物件，您應該傳入您希望連接的屬性鍵，以及您希望放在值之間的「連接」字串：

php

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

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

// 'Desk, Chair'

如果集合包含簡單的字串或數值，您應該將「連接」字串作為唯一引數傳入該方法：

php

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

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

如果您希望格式化正在連接的值，可以傳入一個閉包給 implode 方法：

php

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

// 'DESK, CHAIR'

`intersect()`

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

php

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

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

$intersect->all();

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

📌 備註

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

`intersectUsing()`

intersectUsing 方法會從原始集合中移除任何不在給定陣列或集合中的值，透過使用自訂的回呼函式來比較這些值。結果集合將保留原始集合的鍵：

php

$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 方法會將原始集合與另一個集合或陣列進行比較，回傳存在於所有給定集合中的鍵值對：

php

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

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

$intersect->all();

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

`intersectAssocUsing()`

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

php

$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 方法會從原始集合中移除任何在給定陣列或集合中不存在的鍵及其對應的值：

php

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

php

collect([])->isEmpty();

// true

`isNotEmpty()`

isNotEmpty 方法會在集合不為空時返回 true；否則返回 false：

php

collect([])->isNotEmpty();

// false

`join()`

join 方法會使用一個字串將集合的值連接起來。使用此方法的第二個參數，您還可以指定最後一個元素應如何附加到字串中：

php

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 方法會根據給定的鍵為集合設定鍵。如果有多個項目具有相同的鍵，則只有最後一個項目會出現在新的集合中：

php

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

您也可以傳遞一個回呼給此方法。該回呼應返回用於設定集合鍵的值：

php

$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 方法會返回集合中的所有鍵：

php

$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 方法會返回集合中通過給定真值測試的最後一個元素：

php

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

// 2

您也可以不帶任何參數呼叫 last 方法，以取得集合中的最後一個元素。如果集合為空，則返回 null：

php

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

// 4

`lazy()`

lazy 方法會從底層的項目陣列中返回一個新的 LazyCollection 實例：

php

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

$lazyCollection::class;

// Illuminate\Support\LazyCollection

$lazyCollection->all();

// [1, 2, 3, 4]

當您需要對包含大量項目的大型 Collection 執行轉換時，這特別有用：

php

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

透過將集合轉換為 LazyCollection，我們可以避免分配大量額外記憶體。儘管原始集合仍將其值保留在記憶體中，但後續的過濾器不會。因此，在過濾集合結果時，幾乎不會分配額外的記憶體。

`macro()`

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

`make()`

靜態 make 方法會建立一個新的集合實例。請參閱建立集合章節。

php

use Illuminate\Support\Collection;

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

`map()`

map 方法會迭代集合中的每個項目，並將每個值傳遞給給定的回呼。該回呼可以自由修改項目並將其返回，從而形成一個新的、包含已修改項目的集合：

php

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

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

$multiplied->all();

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

⚠️ 警告

map 方法與大多數其他集合方法一樣，會返回一個新的集合實例；它不會修改被呼叫的集合。如果您想轉換原始集合，請使用 transform 方法。

`mapInto()`

mapInto() 方法會迭代集合，透過將值傳遞給建構函式來建立給定類別的新實例：

php

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 方法會迭代集合中的項目，將每個巢狀項目值傳遞給給定的閉包。該閉包可以自由修改項目並將其返回，從而形成一個新的、包含已修改項目的集合：

php

$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 方法會根據給定的閉包對集合中的項目進行分組。該閉包應返回一個包含單個鍵/值對的關聯陣列，從而形成一個新的分組值集合：

php

$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 方法會迭代集合並將每個值傳遞給指定的回呼。該回呼應該回傳一個包含單一鍵/值對的關聯陣列：

php

$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 方法會回傳指定鍵的最大值：

php

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

// 20

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

// 5

`median()`

median 方法會回傳指定鍵的中位數：

php

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

// 15

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

// 1.5

`merge()`

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

php

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

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

$merged->all();

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

如果指定項目的鍵是數值，這些值將會附加到集合的末端：

php

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

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

$merged->all();

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

`mergeRecursive()`

mergeRecursive 方法會遞迴地將指定的陣列或集合與原始集合合併。如果指定項目中的字串鍵與原始集合中的字串鍵匹配，則這些鍵的值將會合併成一個陣列，並且這個過程會遞迴進行：

php

$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 方法會回傳指定鍵的最小值：

php

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

// 10

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

// 1

`mode()`

mode 方法會回傳指定鍵的眾數：

php

$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 方法會建立集合中所有指定數量項目的副本：

php

$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 個」元素組成的新集合：

php

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

$collection->nth(4);

// ['a', 'e']

您可以選擇性地傳遞一個起始偏移量作為第二個引數：

php

$collection->nth(4, 1);

// ['b', 'f']

`only()`

only 方法會回傳集合中包含指定鍵的項目：

php

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

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

$filtered->all();

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

若要取得 only 的反向操作，請參閱 except 方法。

📌 備註

使用 Eloquent Collections 時，此方法的行為會有所不同。

`pad()`

pad 方法會以指定值填充陣列，直到陣列達到指定大小。此方法的行為類似於 PHP 的 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 陣列解構結合使用，將通過指定真值測試的元素與未通過的元素分開：

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]

📌 備註

與 Eloquent 集合互動時，此方法的行為會有所不同。

`percentage()`

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

php

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

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

// 33.33

預設情況下，百分比將四捨五入到小數點後兩位。然而，您可以透過提供第二個引數來自訂此行為：

php

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

// 33.333

`pipe()`

pipe 方法會將集合傳遞給指定的回呼，並回傳執行回呼的結果：

php

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

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

// 6

`pipeInto()`

pipeInto 方法會建立指定類別的新實例，並將集合傳遞給建構子：

php

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 方法會將集合傳遞給給定的閉包陣列，並回傳這些已執行閉包的結果：

php

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 方法會擷取給定鍵的所有值：

php

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

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

$plucked->all();

// ['Desk', 'Chair']

您也可以指定您希望結果集合如何被鍵化：

php

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

$plucked->all();

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

pluck 方法也支援使用「點」記號來擷取巢狀值：

php

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

如果存在重複的鍵，最後一個匹配的元素將會被插入到擷取的集合中：

php

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

php

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

$collection->pop();

// 5

$collection->all();

// [1, 2, 3, 4]

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

php

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

$collection->pop(3);

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

$collection->all();

// [1, 2]

`prepend()`

prepend 方法會將一個項目添加到集合的開頭：

php

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

$collection->prepend(0);

$collection->all();

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

您也可以傳遞第二個引數來指定要預先添加的項目的鍵：

php

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

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

$collection->all();

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

`pull()`

pull 方法會根據鍵從集合中移除並回傳一個項目：

php

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

$collection->pull('name');

// 'Desk'

$collection->all();

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

`push()`

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

php

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

$collection->push(5);

$collection->all();

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

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

php

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

$collection->push(5, 6, 7);
 
$collection->all();
 
// [1, 2, 3, 4, 5, 6, 7]

`put()`

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

php

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

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

$collection->all();

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

`random()`

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

php

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

$collection->random();

// 4 - (retrieved randomly)

您可以傳遞一個整數給 random 來指定您希望隨機擷取的項目數量。當明確傳遞您希望接收的項目數量時，總會回傳一個項目集合：

php

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

$random->all();

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

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

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

php

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 方法會回傳一個包含指定範圍內整數的集合：

php

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

$collection->all();

// [3, 4, 5, 6]

`reduce()`

reduce 方法會將集合簡化為單一值，並將每次迭代的結果傳遞給後續的迭代：

php

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

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

// 6

第一次迭代中 $carry 的值是 null；然而，您可以透過傳遞第二個引數給 reduce 來指定其初始值：

php

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

// 10

reduce 方法也會將陣列鍵傳遞給給定的回呼：

php

$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 方法類似；然而，它可以接受多個初始值：

php

[$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：

php

$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 方法還會覆寫集合中具有匹配數字鍵的項目：

php

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

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

$replaced->all();

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

`replaceRecursive()`

replaceRecursive 方法的行為類似於 replace，但它會遞迴地進入陣列並對內部值應用相同的替換過程：

php

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

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

$replaced->all();

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

`reverse()`

reverse 方法會反轉集合中項目的順序，並保留原始鍵：

php

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

php

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

$collection->search(4);

// 1

搜尋使用「寬鬆」比較進行，這表示包含整數值的字串將被視為與相同值的整數相等。要使用「嚴格」比較，您可以將 true 作為第二個參數傳遞給該方法：

php

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

// false

或者，您可以提供自己的閉包來搜尋第一個通過給定真值測試的項目：

php

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

// 2

`select()`

select 方法從集合中選取給定的鍵，類似於 SQL SELECT 陳述式：

php

$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 方法從集合中移除並返回第一個項目：

php

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

$collection->shift();

// 1

$collection->all();

// [2, 3, 4, 5]

您可以向 shift 方法傳遞一個整數，以從集合的開頭移除並返回多個項目：

php

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

$collection->shift(3);

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

$collection->all();

// [4, 5]

`shuffle()`

shuffle 方法隨機打亂集合中的項目：

php

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

$shuffled = $collection->shuffle();

$shuffled->all();

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

`skip()`

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

php

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

php

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

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

$subset->all();

// [3, 4]

您也可以向 skipUntil 方法傳遞一個簡單的值，以跳過所有項目直到找到該值：

php

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

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

$subset->all();

// [3, 4]

⚠️ 警告

如果找不到給定的值，或者回呼從未返回 true，則 skipUntil 方法將返回一個空集合。

`skipWhile()`

skipWhile 方法會跳過集合中的項目，直到給定的回呼返回 true。一旦回呼返回 false，集合中所有剩餘的項目將作為一個新集合返回：

php

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

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

$subset->all();

// [4]

⚠️ 警告

如果回呼從未返回 false，則 skipWhile 方法將返回一個空集合。

`slice()`

slice 方法返回從給定索引開始的集合切片：

php

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

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

$slice->all();

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

如果您想限制返回切片的大小，請將所需大小作為方法的第二個參數傳遞：

php

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

$slice->all();

// [5, 6]

默認情況下，返回的切片將保留鍵。如果您不希望保留原始鍵，可以使用 values 方法重新索引它們。

`sliding()`

sliding 方法返回一個新的分塊集合，代表集合中項目的「滑動視窗」視圖：

php

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

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

$chunks->toArray();

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

這與 eachSpread 方法結合使用時特別有用：

php

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

您可以選擇傳遞第二個「step」值，它決定了每個分塊中第一個項目之間的距離：

php

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

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

$chunks->toArray();

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

`sole()`

sole 方法返回集合中第一個通過給定真值測試的元素，但前提是該真值測試僅匹配一個元素：

php

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

// 2

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

php

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

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

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

或者，您也可以在不傳遞任何參數的情況下呼叫 sole 方法，以在集合中只有一個元素時取得第一個元素：

php

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

$collection->sole();

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

如果集合中沒有元素應由 sole 方法返回，則將拋出 \Illuminate\Collections\ItemNotFoundException 異常。如果有多個元素應返回，則將拋出 \Illuminate\Collections\MultipleItemsFoundException 異常。

`some()`

contains 方法的別名。

`sort()`

sort 方法會排序集合。已排序的集合會保留原始陣列的鍵，所以在以下範例中，我們會使用 values 方法將鍵重設為連續的數字索引：

php

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

$sorted = $collection->sort();

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

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

如果您的排序需求更為進階，您可以傳遞一個回呼函式給 sort 並使用您自己的演算法。請參考 PHP 文件中的 uasort，這是集合的 sort 方法內部所利用的 PHP 函式。

📌 備註

如果您需要排序巢狀陣列或物件的集合，請參考 sortBy 和 sortByDesc 方法。

`sortBy()`

sortBy 方法會根據給定的鍵來排序集合。已排序的集合會保留原始陣列的鍵，所以在以下範例中，我們會使用 values 方法將鍵重設為連續的數字索引：

php

$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 方法接受排序旗標 (sort flags) 作為其第二個參數：

php

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

或者，您可以傳遞一個自訂的回呼函式來決定如何排序集合的值：

php

$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 方法。每個排序操作都應是一個陣列，包含您希望排序的屬性以及所需的排序方向：

php

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

當根據多個屬性排序集合時，您也可以提供定義每個排序操作的回呼函式：

php

$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 方法相反的順序排序集合：

php

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

$sorted = $collection->sortDesc();

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

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

與 sort 不同，您不能傳遞回呼函式給 sortDesc。相反地，您應該使用 sort 方法並反轉您的比較。

`sortKeys()`

sortKeys 方法會根據底層關聯陣列的鍵來排序集合：

php

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

$sorted = $collection->sortKeys();

$sorted->all();

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

`sortKeysDesc()`

此方法與 sortKeys 方法的簽名相同，但會以相反的順序排序集合。

`sortKeysUsing()`

sortKeysUsing 方法會使用回呼函式，根據底層關聯陣列的鍵來排序集合：

php

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

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

$sorted->all();

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

該回呼函式必須是一個比較函式，回傳一個小於、等於或大於零的整數。欲瞭解更多資訊，請參考 PHP 文件中的 uksort，這是 sortKeysUsing 方法內部利用的 PHP 函式。

`splice()`

splice 方法會從指定索引處移除並回傳一個項目切片：

php

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

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

$chunk->all();

// [3, 4, 5]

$collection->all();

// [1, 2]

您可以傳遞第二個參數來限制結果集合的大小：

php

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

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

$chunk->all();

// [3]

$collection->all();

// [1, 2, 4, 5]

此外，您可以傳遞第三個參數，其中包含要替換從集合中移除的項目的新項目：

php

$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 方法會將集合分割成給定數量的群組：

php

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

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

$groups->all();

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

`splitIn()`

splitIn 方法會將集合分割成給定數量的群組，在將剩餘部分分配給最後一個群組之前，會先完全填滿非終端群組：

php

$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 方法回傳集合中所有項目的總和：

php

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

// 15

如果集合中包含巢狀陣列或物件，則應傳遞一個鍵，該鍵將用於決定要加總哪些值：

php

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

$collection->sum('pages');

// 1272

此外，您也可以傳遞自己的閉包來決定集合中要加總哪些值：

php

$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 方法回傳一個包含指定數量項目新集合：

php

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

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

$chunk->all();

// [0, 1, 2]

您也可以傳遞一個負整數來從集合的末端取得指定數量的項目：

php

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

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

$chunk->all();

// [4, 5]

`takeUntil()`

takeUntil 方法回傳集合中的項目，直到給定的回呼函式回傳 true 為止：

php

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

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

$subset->all();

// [1, 2]

您也可以傳遞一個簡單的值給 takeUntil 方法，以取得直到找到該值為止的項目：

php

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

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

$subset->all();

// [1, 2]

⚠️ 警告

如果找不到給定的值或回呼函式從未回傳 true，takeUntil 方法將回傳集合中的所有項目。

`takeWhile()`

takeWhile 方法回傳集合中的項目，直到給定的回呼函式回傳 false 為止：

php

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

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

$subset->all();

// [1, 2]

⚠️ 警告

如果回呼函式從未回傳 false，takeWhile 方法將回傳集合中的所有項目。

`tap()`

tap 方法將集合傳遞給指定的回呼函式，讓您可以在特定時間點「介入 (tap)」集合並對項目執行某些操作，同時不影響集合本身。然後 tap 方法會回傳該集合：

php

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

// 1

`times()`

靜態的 times 方法透過呼叫給定的閉包指定次數來建立一個新的集合：

php

$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 模型，這些模型也將被轉換為陣列：

php

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

$collection->toArray();

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

⚠️ 警告

toArray 也會將集合中所有為 Arrayable 實例的巢狀物件轉換為陣列。如果您想取得集合底層的原始陣列，請改用 all 方法。

`toJson()`

toJson 方法將集合轉換為 JSON 序列化字串：

php

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

$collection->toJson();

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

`toPrettyJson()`

toPrettyJson 方法使用 JSON_PRETTY_PRINT 選項將集合轉換為格式化的 JSON 字串：

php

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

$collection->toPrettyJson();

`transform()`

transform 方法會迭代集合，並針對集合中的每個項目呼叫指定的回呼函式。集合中的項目將被回呼函式回傳的值所取代：

php

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

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

$collection->all();

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

⚠️ 警告

與大多數其他集合方法不同，transform 會修改集合本身。如果您希望建立一個新集合，請使用 map 方法。

`undot()`

undot 方法將使用「點 (dot)」標記法的一維集合展開為多維集合：

php

$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 方法將給定的陣列新增到集合中。如果給定陣列包含已在原始集合中的鍵，則原始集合的值將優先被保留：

php

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

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

$union->all();

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

`unique()`

unique 方法回傳集合中所有唯一項目。回傳的集合會保留原始的陣列鍵，因此在以下範例中，我們將使用 values 方法來將鍵重設為連續的數字索引：

php

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

$unique = $collection->unique();

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

// [1, 2, 3, 4]

處理巢狀陣列或物件時，您可以指定用於判斷唯一性的鍵：

php

$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 方法，以指定哪個值應該決定項目的唯一性：

php

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

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

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

unique 方法在檢查項目值時使用「寬鬆」比較，這表示一個包含整數值的字串將被視為與相同值的整數相等。若要使用「嚴格」比較進行篩選，請使用 uniqueStrict 方法。

📌 備註

使用 Eloquent Collections 時，此方法的行為會有所修改。

`uniqueStrict()`

此方法與 unique 方法具有相同的簽章；然而，所有值都使用「嚴格」比較進行比較。

`unless()`

unless 方法會在傳給該方法的第一個參數評估為 true 時不執行指定的閉包。集合實例和傳給 unless 方法的第一個參數將提供給閉包：

php

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

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

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

$collection->all();

// [1, 2, 3, 5]

第二個閉包可以傳遞給 unless 方法。當傳給 unless 方法的第一個參數評估為 true 時，將執行第二個閉包：

php

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

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

$collection->all();

// [1, 2, 3, 5]

若要取得 unless 的反向操作，請參閱 when 方法。

`unlessEmpty()`

whenNotEmpty 方法的別名。

`unlessNotEmpty()`

whenEmpty 方法的別名。

`unwrap()`

靜態 unwrap 方法在適用時從給定值回傳集合的底層項目：

php

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

// ['John Doe']

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

// ['John Doe']

Collection::unwrap('John Doe');

// 'John Doe'

`value()`

value 方法從集合的第一個元素中檢索給定值：

php

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

$value = $collection->value('price');

// 200

`values()`

values 方法回傳一個新集合，其鍵已重設為連續的整數：

php

$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 方法的第一個參數將提供給閉包：

php

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

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

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

$collection->all();

// [1, 2, 3, 4]

第二個閉包可以傳遞給 when 方法。當傳給 when 方法的第一個參數評估為 false 時，將執行第二個閉包：

php

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

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

$collection->all();

// [1, 2, 3, 5]

若要取得 when 的反向操作，請參閱 unless 方法。

`whenEmpty()`

whenEmpty 方法會在集合為空時執行指定的閉包：

php

$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 方法，該閉包會在集合不為空時執行：

php

$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 方法會在集合不為空時執行指定的閉包：

php

$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 方法，該閉包會在集合為空時執行：

php

$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 方法會透過給定的鍵/值對來篩選集合：

php

$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 方法進行「嚴格」比較篩選，或使用 whereNull 和 whereNotNull 方法篩選 null 值。

您可以選擇將比較運算子作為第二個參數傳入。支援的運算子包括：'===', '!==', '!=', '==', '=', '<>', '>', '<', '>=', 和 '<='：

php

$collection = collect([
    ['name' => 'Jim', 'platform' => 'Mac'],
    ['name' => 'Sally', 'platform' => 'Mac'],
    ['name' => 'Sue', 'platform' => 'Linux'],
]);

$filtered = $collection->where('platform', '!=', 'Linux');

$filtered->all();

/*
    [
        ['name' => 'Jim', 'platform' => 'Mac'],
        ['name' => 'Sally', 'platform' => 'Mac'],
    ]
*/

`whereStrict()`

此方法與 where 方法有相同的方法簽章；不過，所有值都會使用「嚴格」比較來進行比較。

`whereBetween()`

whereBetween 方法會透過判斷指定的項目值是否在給定範圍內來篩選集合：

php

$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 方法會從集合中移除那些其指定項目值未包含在給定陣列中的元素：

php

$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 方法會根據給定的類別型別來篩選集合：

php

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 方法會透過判斷指定的項目值是否在給定範圍之外來篩選集合：

php

$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 方法會從集合中移除那些其指定項目值包含在給定陣列中的元素：

php

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

$filtered = $collection->whereNotIn('price', [150, 200]);

$filtered->all();

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

whereNotIn 方法在檢查項目值時會使用「寬鬆」比較，這表示帶有整數值的字串將被視為與相同值的整數相等。請使用 whereNotInStrict 方法進行「嚴格」比較篩選。

`whereNotInStrict()`

此方法與 whereNotIn 方法有相同的方法簽章；不過，所有值都會使用「嚴格」比較來進行比較。

`whereNotNull()`

whereNotNull 方法會從集合中回傳指定鍵不為 null 的項目：

php

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

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

$filtered->all();

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

`whereNull()`

whereNull 方法會從集合中回傳指定鍵為 null 的項目：

php

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

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

$filtered->all();

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

`wrap()`

靜態 wrap 方法會在適用時將給定值包裝成一個集合：

php

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 方法會將給定陣列中的值與原始集合中對應索引的值合併在一起：

php

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

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

$zipped->all();

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

高階訊息

Collections 也支援「高階訊息」，這是對集合執行常見操作的捷徑。提供高階訊息的集合方法有：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 高階訊息來呼叫集合中每個物件上的方法：

php

use App\Models\User;

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

$users->each->markAsVip();

同樣地，我們可以使用 sum 高階訊息來收集使用者集合中「票數」的總和：

php

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

return $users->sum->votes;

惰性集合

簡介

⚠️ 警告

在深入了解 Laravel 的惰性集合之前，請花一些時間熟悉 PHP 產生器。

為補充功能強大的 Collection 類別，LazyCollection 類別利用 PHP 的產生器讓您能夠處理非常龐大的資料集，同時保持記憶體使用量低。

例如，想像您的應用程式需要處理一個數 GB 大小的日誌檔，並利用 Laravel 的集合方法來解析日誌。惰性集合可以在不一次將整個檔案讀入記憶體的情況下，在任何給定時間只將檔案的一小部分保留在記憶體中：

php

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

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

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

    fclose($handle);
})->chunk(4)->map(function (array $lines) {
    return LogEntry::fromLines($lines);
})->each(function (LogEntry $logEntry) {
    // Process the log entry...
});

或者，想像您需要迭代 10,000 個 Eloquent 模型。使用傳統 Laravel 集合時，所有 10,000 個 Eloquent 模型都必須同時載入到記憶體中：

php

use App\Models\User;

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

然而，查詢產生器的 cursor 方法會返回一個 LazyCollection 實例。這讓您仍然可以只對資料庫執行單一查詢，同時在記憶體中只保留一個 Eloquent 模型。在此範例中，filter 回呼函式在我們實際單獨迭代每個使用者之前不會執行，從而大幅降低了記憶體使用量：

php

use App\Models\User;

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

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

建立惰性集合

要建立惰性集合實例，您應該將 PHP 產生器函式傳遞給集合的 make 方法：

php

use Illuminate\Support\LazyCollection;

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

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

    fclose($handle);
});

Enumerable 契約

幾乎所有 Collection 類別中可用的方法在 LazyCollection 類別中也可用。這兩個類別都實作了 Illuminate\Support\Enumerable 契約，該契約定義了以下方法：

⚠️ 警告

會改變集合的方法 (例如 shift、pop、prepend 等) 不適用於 LazyCollection 類別。

惰性集合方法

除了 Enumerable 契約中定義的方法外，LazyCollection 類別還包含以下方法：

`takeUntilTimeout()`

takeUntilTimeout 方法會回傳一個新的惰性集合，該集合將枚舉 (enumerate) 值直到指定時間。過該時間後，該集合將停止枚舉：

php

$lazyCollection = LazyCollection::times(INF)
    ->takeUntilTimeout(now()->plus(minutes: 1));

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

    sleep(1);
});

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

為了說明此方法的用法，想像一個應用程式使用游標從資料庫提交發票。您可以定義一個排程任務，該任務每 15 分鐘執行一次，並且只處理最多 14 分鐘的發票：

php

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 方法會立即呼叫給定的回呼 (callback) 處理集合中的每個項目，而 tapEach 方法僅在項目一個一個地從列表中取出時才呼叫給定的回呼：

php

// Nothing has been dumped so far...
$lazyCollection = LazyCollection::times(INF)->tapEach(function (int $value) {
    dump($value);
});

// Three items are dumped...
$array = $lazyCollection->take(3)->all();

// 1
// 2
// 3

`throttle()`

throttle 方法會對惰性集合進行節流 (throttle)，使得每個值在指定的秒數後才回傳。此方法對於您可能與限制傳入請求速率的外部 API 互動的情況特別有用：

php

use App\Models\User;

User::where('vip', true)
    ->cursor()
    ->throttle(seconds: 1)
    ->each(function (User $user) {
        // Call external API...
    });

`remember()`

remember 方法回傳一個新的惰性集合，該集合會記住任何已枚舉 (enumerated) 的值，並且不會在後續的集合枚舉中再次檢索它們：

php

// No query has been executed yet...
$users = User::cursor()->remember();

// The query is executed...
// The first 5 users are hydrated from the database...
$users->take(5)->all();

// First 5 users come from the collection's cache...
// The rest are hydrated from the database...
$users->take(20)->all();

`withHeartbeat()`

withHeartbeat 方法允許您在惰性集合被枚舉時，以固定的時間間隔執行回呼。這對於需要定期維護任務（例如延長鎖定或傳送進度更新）的長時間執行操作特別有用：

php

use Carbon\CarbonInterval;
use Illuminate\Support\Facades\Cache;

$lock = Cache::lock('generate-reports', seconds: 60 * 5);

if ($lock->get()) {
    try {
        Report::where('status', 'pending')
            ->lazy()
            ->withHeartbeat(
                CarbonInterval::minutes(4),
                fn () => $lock->extend(CarbonInterval::minutes(5))
            )
            ->each(fn ($report) => $report->process());
    } finally {
        $lock->release();
    }
}

Collections ​

簡介 ​

建立集合 ​

擴充集合 ​

Macro 引數 ​

可用方法 ​

方法列表 ​

after() ​

all() ​

average() ​

avg() ​

before() ​

chunk() ​

chunkWhile() ​

collapse() ​

collapseWithKeys() ​

collect() ​

combine() ​

concat() ​

contains() ​

containsOneItem() ​

containsStrict() ​

count() ​

countBy() ​

crossJoin() ​

dd() ​

diff() ​

diffAssoc() ​

diffAssocUsing() ​

diffKeys() ​

doesntContain() ​

doesntContainStrict() ​

dot() ​

dump() ​

duplicates() ​

duplicatesStrict() ​

each() ​

eachSpread() ​

ensure() ​

every() ​

except() ​

filter() ​

first() ​

firstOrFail() ​

firstWhere() ​

flatMap() ​

flatten() ​

flip() ​

forget() ​

forPage() ​

fromJson() ​

get() ​

groupBy() ​

has() ​

hasAny() ​

implode() ​

intersect() ​

intersectUsing() ​

intersectAssoc() ​

intersectAssocUsing() ​

intersectByKeys() ​

isEmpty() ​

isNotEmpty() ​

join() ​

keyBy() ​

keys() ​

last() ​

lazy() ​

macro() ​

make() ​

map() ​

mapInto() ​

mapSpread() ​

mapToGroups() ​

mapWithKeys() ​

max() ​

median() ​

merge() ​

mergeRecursive() ​

min() ​

Collections

簡介

建立集合

擴充集合

Macro 引數

可用方法

方法列表

`after()`

`all()`

`average()`

`avg()`

`before()`

`chunk()`

`chunkWhile()`

`collapse()`

`collapseWithKeys()`

`collect()`

`combine()`

`concat()`

`contains()`

`containsOneItem()`

`containsStrict()`

`count()`

`countBy()`

`crossJoin()`

`dd()`

`diff()`

`diffAssoc()`

`diffAssocUsing()`

`diffKeys()`

`doesntContain()`

`doesntContainStrict()`

`dot()`

`dump()`

`duplicates()`

`duplicatesStrict()`

`each()`

`eachSpread()`

`ensure()`

`every()`

`except()`

`filter()`

`first()`

`firstOrFail()`

`firstWhere()`

`flatMap()`

`flatten()`

`flip()`

`forget()`

`forPage()`

`fromJson()`

`get()`

`groupBy()`

`has()`

`hasAny()`

`implode()`

`intersect()`

`intersectUsing()`

`intersectAssoc()`

`intersectAssocUsing()`

`intersectByKeys()`

`isEmpty()`

`isNotEmpty()`

`join()`

`keyBy()`

`keys()`

`last()`

`lazy()`

`macro()`

`make()`

`map()`

`mapInto()`

`mapSpread()`

`mapToGroups()`

`mapWithKeys()`

`max()`

`median()`

`merge()`

`mergeRecursive()`

`min()`