集合

• 簡介
  • 建立集合
  • 擴展集合
• 可用的方法
• 高階訊息
• 惰性集合
  • 簡介
  • 建立惰性集合
  • 可列舉合約
  • 惰性集合方法

簡介

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

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

如您所見，Collection 類別允許您鏈接其方法來執行基礎陣列的流暢映射和縮減。一般而言，集合是不可變的，這意味著每個 Collection 方法都會傳回一個全新的 Collection 實例。

建立集合

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

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

擴展集合

集合是「可巨集化的」，這允許您在執行時向 Collection 類別新增額外的方法。Illuminate\Support\Collection 類別的 macro 方法接受一個閉包，該閉包將在呼叫您的巨集時執行。巨集閉包可以透過 $this 存取集合的其他方法，就像它是集合類別的真實方法一樣。例如，以下程式碼將 toUpper 方法新增到 Collection 類別

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

通常，您應該在服務提供者的 boot 方法中宣告集合巨集。

巨集引數

如果需要，您可以定義接受額外引數的巨集

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

可用的方法

在剩餘的大部分集合文件中，我們將討論 Collection 類別上可用的每個方法。請記住，所有這些方法都可以鏈接起來，以流暢地操作基礎陣列。此外，幾乎每個方法都會傳回一個新的 Collection 實例，允許您在必要時保留集合的原始副本

方法列表

after()

after 方法會回傳指定項目之後的項目。如果找不到指定項目或該項目是最後一個項目，則會回傳 null。

$collection = collect([1, 2, 3, 4, 5]);
 
$collection->after(3);
 
// 4
 
$collection->after(5);
 
// null

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

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

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

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

all()

all 方法會回傳集合所代表的底層陣列。

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

average()

avg 方法的別名。

avg()

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

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

before()

before 方法與 after 方法相反。它會回傳指定項目之前的項目。如果找不到指定項目或該項目是第一個項目，則會回傳 null。

$collection = collect([1, 2, 3, 4, 5]);
 
$collection->before(3);
 
// 2
 
$collection->before(1);
 
// null
 
collect([2, 4, 6, 8])->before('4', strict: true);
 
// null
 
collect([2, 4, 6, 8])->before(function (int $item, int $key) {
    return $item > 5;
});
 
// 4

chunk()

chunk 方法會將集合分割成多個較小的、具有指定大小的集合。

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

當使用像 Bootstrap 之類的網格系統時，此方法在 視圖中特別有用。例如，假設您有一個想要在網格中顯示的 Eloquent 模型集合。

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

chunkWhile()

chunkWhile 方法會根據給定回呼的評估，將集合分割成多個較小的集合。傳遞給閉包的 $chunk 變數可以用來檢查前一個元素。

$collection = collect(str_split('AABBCCCD'));
 
$chunks = $collection->chunkWhile(function (string $value, int $key, Collection $chunk) {
    return $value === $chunk->last();
});
 
$chunks->all();
 
// [['A', 'A'], ['B', 'B'], ['C', 'C', 'C'], ['D']]

collapse()

collapse 方法會將陣列集合摺疊成單一的平面集合。

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

collect()

collect 方法會回傳一個新的 Collection 實例，其中包含集合中目前的項目。

$collectionA = collect([1, 2, 3]);
 
$collectionB = $collectionA->collect();
 
$collectionB->all();
 
// [1, 2, 3]

collect 方法主要用於將惰性集合轉換為標準的 Collection 實例。

$lazyCollection = LazyCollection::make(function () {
    yield 1;
    yield 2;
    yield 3;
});
 
$collection = $lazyCollection->collect();
 
$collection::class;
 
// 'Illuminate\Support\Collection'
 
$collection->all();
 
// [1, 2, 3]

combine()

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

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

concat()

concat 方法會將給定的 array 或集合的值附加到另一個集合的末端。

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

concat 方法會為附加到原始集合的項目重新以數字編排索引。若要在關聯式集合中保留鍵，請參閱 merge 方法。

contains()

contains 方法會判斷集合是否包含指定的項目。您可以將閉包傳遞給 contains 方法，以判斷集合中是否存在符合給定真值測試的元素。

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

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

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

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

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

contains 方法在檢查項目值時使用「寬鬆」比較，這表示具有整數值的字串會被視為與相同值的整數相等。使用 containsStrict 方法來使用「嚴格」比較篩選。

如需 contains 的反向，請參閱 doesntContain 方法。

containsOneItem()

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

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

containsStrict()

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

count()

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

$collection = collect([1, 2, 3, 4]);
 
$collection->count();
 
// 4

countBy()

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

$collection = collect([1, 2, 2, 2, 3]);
 
$counted = $collection->countBy();
 
$counted->all();
 
// [1 => 1, 2 => 3, 3 => 1]

您可以將閉包傳遞給 countBy 方法，以依自訂值計算所有項目。

$collection = collect(['[email protected]', '[email protected]', '[email protected]']);
 
$counted = $collection->countBy(function (string $email) {
    return substr(strrchr($email, "@"), 1);
});
 
$counted->all();
 
// ['gmail.com' => 2, 'yahoo.com' => 1]

crossJoin()

crossJoin 方法會在給定的陣列或集合之間交叉聯結集合的值，並回傳具有所有可能排列方式的笛卡爾積。

$collection = collect([1, 2]);
 
$matrix = $collection->crossJoin(['a', 'b']);
 
$matrix->all();
 
/*
    [
        [1, 'a'],
        [1, 'b'],
        [2, 'a'],
        [2, 'b'],
    ]
*/
 
$collection = collect([1, 2]);
 
$matrix = $collection->crossJoin(['a', 'b'], ['I', 'II']);
 
$matrix->all();
 
/*
    [
        [1, 'a', 'I'],
        [1, 'a', 'II'],
        [1, 'b', 'I'],
        [1, 'b', 'II'],
        [2, 'a', 'I'],
        [2, 'a', 'II'],
        [2, 'b', 'I'],
        [2, 'b', 'II'],
    ]
*/

dd()

dd 方法會傾印集合的項目並結束指令碼的執行。

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

如果您不想停止執行指令碼，請改用 dump 方法。

diff()

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

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

diffAssoc()

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

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

diffAssocUsing()

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

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

回呼必須是傳回小於、等於或大於零的整數的比較函數。如需更多資訊，請參閱 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]);
 
$collection->doesntContain(function (int $value, int $key) {
    return $value < 5;
});
 
// false

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

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

您也可以將鍵/值對傳遞給 doesntContain 方法，這會判斷集合中是否存在指定的配對。

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

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

dot()

dot 方法會將多維集合扁平化為單一級別的集合，該集合使用「點」表示法來指示深度。

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

dump()

dump 方法會傾印集合的項目。

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

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

duplicates()

duplicates 方法會從集合中擷取並回傳重複的值。

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

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

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

duplicatesStrict()

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

each()

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

$collection = collect([1, 2, 3, 4]);
 
$collection->each(function (int $item, int $key) {
    // ...
});

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

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

eachSpread()

eachSpread 方法會迭代集合的項目，將每個巢狀項目值傳遞到給定的回呼函數中。

$collection = collect([['John Doe', 35], ['Jane Doe', 33]]);
 
$collection->eachSpread(function (string $name, int $age) {
    // ...
});

您可以通過從回呼函數返回 false 來停止迭代項目。

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

ensure()

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

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

也可以指定諸如 string、int、float、bool 和 array 等基本類型。

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

every()

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

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

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

$collection = collect([]);
 
$collection->every(function (int $value, int $key) {
    return $value > 2;
});
 
// true

except()

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

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

有關 except 的反向操作，請參閱 only 方法。

filter()

filter 方法使用給定的回呼函數過濾集合，僅保留通過給定真值測試的項目。

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

如果沒有提供回呼函數，則會移除集合中所有等同於 false 的項目。

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

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

first()

first 方法會返回集合中通過給定真值測試的第一個元素。

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

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

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

firstOrFail()

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

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

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

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

firstWhere()

firstWhere 方法會返回集合中具有給定鍵/值配對的第一個元素。

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

您也可以使用比較運算符呼叫 firstWhere 方法。

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

與 where 方法類似，您可以傳遞一個參數給 firstWhere 方法。在這種情況下，firstWhere 方法會返回給定項目鍵的值為「真值」的第一個項目。

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

forPage()

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

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

get()

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

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

您可以選擇性地傳遞一個預設值作為第二個參數。

$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
 
$value = $collection->get('age', 34);
 
// 34

您甚至可以將回呼函數作為方法的預設值傳遞。如果指定的鍵不存在，則會返回回呼函數的結果。

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

groupBy()

groupBy 方法會依給定鍵對集合的項目進行分組。

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

您可以傳遞一個回呼函數，而不是傳遞字串 key。回呼函數應返回您希望用來分組的值。

$grouped = $collection->groupBy(function (array $item, int $key) {
    return substr($item['account_id'], -3);
});
 
$grouped->all();
 
/*
    [
        'x10' => [
            ['account_id' => 'account-x10', 'product' => 'Chair'],
            ['account_id' => 'account-x10', 'product' => 'Bookcase'],
        ],
        'x11' => [
            ['account_id' => 'account-x11', 'product' => 'Desk'],
        ],
    ]
*/

可以將多個分組條件作為陣列傳遞。每個陣列元素將被應用到多維陣列中的相應層級。

$data = new Collection([
    10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
    20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
    30 => ['user' => 3, 'skill' => 2, 'roles' => ['Role_1']],
    40 => ['user' => 4, 'skill' => 2, 'roles' => ['Role_2']],
]);
 
$result = $data->groupBy(['skill', function (array $item) {
    return $item['roles'];
}], preserveKeys: true);
 
/*
[
    1 => [
        'Role_1' => [
            10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
            20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
        ],
        'Role_2' => [
            20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
        ],
        'Role_3' => [
            10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
        ],
    ],
    2 => [
        'Role_1' => [
            30 => ['user' => 3, 'skill' => 2, 'roles' => ['Role_1']],
        ],
        'Role_2' => [
            40 => ['user' => 4, 'skill' => 2, 'roles' => ['Role_2']],
        ],
    ],
];
*/

has()

has 方法會判斷集合中是否存在給定的鍵。

$collection = collect(['account_id' => 1, 'product' => 'Desk', 'amount' => 5]);
 
$collection->has('product');
 
// true
 
$collection->has(['product', 'amount']);
 
// true
 
$collection->has(['amount', 'price']);
 
// false

hasAny()

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

$collection = collect(['account_id' => 1, 'product' => 'Desk', 'amount' => 5]);
 
$collection->hasAny(['product', 'price']);
 
// true
 
$collection->hasAny(['name', 'price']);
 
// false

implode()

implode 方法會聯接集合中的項目。其參數取決於集合中項目的類型。如果集合包含陣列或物件，您應該傳遞您要聯接的屬性的鍵，以及您希望放在值之間的「膠水」字串。

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

如果集合包含簡單的字串或數值，則您應該將「膠水」作為方法的唯一參數傳遞。

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

如果您想要格式化被聯接的值，可以傳遞一個閉包給 implode 方法。

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

intersect()

intersect 方法會從原始集合中移除給定 array 或集合中不存在的任何值。產生的集合將保留原始集合的鍵。

$collection = collect(['Desk', 'Sofa', 'Chair']);
 
$intersect = $collection->intersect(['Desk', 'Chair', 'Bookcase']);
 
$intersect->all();
 
// [0 => 'Desk', 2 => 'Chair']

intersectAssoc()

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

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

intersectByKeys()

intersectByKeys 方法會從原始集合中移除給定 array 或集合中不存在的任何鍵及其對應的值。

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

isEmpty()

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

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

isNotEmpty()

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

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

join()

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

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

keyBy()

keyBy 方法會依給定鍵來設定集合的鍵。如果多個項目具有相同的鍵，則只有最後一個會出現在新的集合中。

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

您也可以將回呼函數傳遞給該方法。回呼函數應返回要設定集合鍵的值。

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

keys()

keys 方法會返回集合的所有鍵。

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

last()

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

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

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

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

lazy()

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

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

當您需要對包含許多項目的大型 Collection 執行轉換時，這尤其有用。

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

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

macro()

靜態 macro 方法可讓您在運行時將方法添加到 Collection 類別。有關更多資訊，請參閱有關擴展集合的文件。

make()

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

map()

map 方法會迭代集合，並將每個值傳遞給給定的回呼函數。回呼函數可以自由地修改項目並返回它，從而形成一個新的修改項目集合。

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

mapInto()

mapInto() 方法會迭代集合，通過將值傳遞到建構子中來建立給定類別的新實例。

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

mapSpread()

mapSpread 方法會迭代集合的項目，將每個巢狀項目值傳遞到給定的閉包。閉包可以自由地修改項目並返回它，從而形成一個新的修改項目集合。

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

mapToGroups()

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

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

mapWithKeys()

mapWithKeys 方法會迭代集合，並將每個值傳遞給給定的回呼函數。回呼函數應返回一個包含單個鍵/值對的關聯陣列。

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

max()

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

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

median()

median 方法會返回給定鍵的中位數值。

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

merge()

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

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

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

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

mergeRecursive()

mergeRecursive 方法會將給定的陣列或集合以遞迴方式與原始集合合併。如果給定項目中的字串鍵與原始集合中的字串鍵匹配，則這些鍵的值會合併到一個陣列中，並且此操作會遞迴進行

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

min()

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

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

mode()

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

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

multiply()

multiply 方法會建立集合中所有項目的指定份數副本

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

nth()

nth 方法會建立一個新的集合，其中包含每第 n 個元素

$collection = collect(['a', 'b', 'c', 'd', 'e', 'f']);
 
$collection->nth(4);
 
// ['a', 'e']

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

$collection->nth(4, 1);
 
// ['b', 'f']

only()

only 方法會返回集合中具有指定鍵的項目

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

如需 only 的反向操作，請參閱 except 方法。

pad()

pad 方法會使用給定的值填充陣列，直到陣列達到指定的大小。此方法的行為類似於 array_pad PHP 函數。

若要向左填充，您應該指定負數大小。如果給定大小的絕對值小於或等於陣列的長度，則不會進行填充

$collection = collect(['A', 'B', 'C']);
 
$filtered = $collection->pad(5, 0);
 
$filtered->all();
 
// ['A', 'B', 'C', 0, 0]
 
$filtered = $collection->pad(-5, 0);
 
$filtered->all();
 
// [0, 0, 'A', 'B', 'C']

partition()

partition 方法可以與 PHP 陣列解構結合使用，以將通過給定真值測試的元素與未通過測試的元素分開

$collection = collect([1, 2, 3, 4, 5, 6]);
 
[$underThree, $equalOrAboveThree] = $collection->partition(function (int $i) {
    return $i < 3;
});
 
$underThree->all();
 
// [1, 2]
 
$equalOrAboveThree->all();
 
// [3, 4, 5, 6]

percentage()

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

$collection = collect([1, 1, 2, 2, 2, 3]);
 
$percentage = $collection->percentage(fn ($value) => $value === 1);
 
// 33.33

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

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

pipe()

pipe 方法會將集合傳遞給給定的閉包，並返回執行閉包的結果

$collection = collect([1, 2, 3]);
 
$piped = $collection->pipe(function (Collection $collection) {
    return $collection->sum();
});
 
// 6

pipeInto()

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

class ResourceCollection
{
    /**
     * Create a new ResourceCollection instance.
     */
    public function __construct(
        public Collection $collection,
    ) {}
}
 
$collection = collect([1, 2, 3]);
 
$resource = $collection->pipeInto(ResourceCollection::class);
 
$resource->collection->all();
 
// [1, 2, 3]

pipeThrough()

pipeThrough 方法會將集合傳遞給給定的閉包陣列，並返回執行閉包的結果

use Illuminate\Support\Collection;
 
$collection = collect([1, 2, 3]);
 
$result = $collection->pipeThrough([
    function (Collection $collection) {
        return $collection->merge([4, 5]);
    },
    function (Collection $collection) {
        return $collection->sum();
    },
]);
 
// 15

pluck()

pluck 方法會檢索給定鍵的所有值

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