Collection

簡介

Illuminate\Support\Collection 類別為處理陣列資料提供了一個流暢且便利的包裝。舉例來說,看看下列程式碼。我們會使用 collect 輔助函式來自陣列建立一個新的 Collection 實體,然後在每個元素上執行 strtoupper 函式,並移除所有空元素:

1$collection = collect(['taylor', 'abigail', null])->map(function ($name) {
2 return strtoupper($name);
3})->reject(function ($name) {
4 return empty($name);
5});
1$collection = collect(['taylor', 'abigail', null])->map(function ($name) {
2 return strtoupper($name);
3})->reject(function ($name) {
4 return empty($name);
5});

如你所見,Collection 類別能讓你將其方法串在一起呼叫,以流暢地在底層的陣列上進行 Map 與 Reduce 處理。通常來說,Collection 是不可變的(Immutable),這代表每個 Collection 方法都會回傳一個全新的 Collection 實體。

建立 Collection

就像上面提到的一樣,collect 輔助函式會為給定的陣列回傳一個新的 Illuminate\Support\Collection 實體。因此,建立 Collection 就這麼簡單:

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

Eloquent 查詢的結果總會回傳為 Collection 實體。

擴充 Collection

Collection 是「Macroable (可巨集)」的,這代表我們可以在執行階段往 Collection 增加額外的方法。Illuminate\Support\Collection 類別的 macro 方法接收一個閉包,該閉包會在 Macro 被呼叫時執行。Macro 閉包也能像真正的 Collection 類別方法一樣,通過 $this 來存取該 Collection 的其他方法。舉例來說,下列程式碼會往 Collection 類別內新增一個 toUpper 方法:

1use Illuminate\Support\Collection;
2use Illuminate\Support\Str;
3 
4Collection::macro('toUpper', function () {
5 return $this->map(function ($value) {
6 return Str::upper($value);
7 });
8});
9 
10$collection = collect(['first', 'second']);
11 
12$upper = $collection->toUpper();
13 
14// ['FIRST', 'SECOND']
1use Illuminate\Support\Collection;
2use Illuminate\Support\Str;
3 
4Collection::macro('toUpper', function () {
5 return $this->map(function ($value) {
6 return Str::upper($value);
7 });
8});
9 
10$collection = collect(['first', 'second']);
11 
12$upper = $collection->toUpper();
13 
14// ['FIRST', 'SECOND']

一般來說,Collection Macro 的宣告應放置於某個 Service Providerboot 方法內。

Macro 引數

若有需要,也可以定義接受額外引數的 Macro:

1use Illuminate\Support\Collection;
2use Illuminate\Support\Facades\Lang;
3 
4Collection::macro('toLocale', function ($locale) {
5 return $this->map(function ($value) use ($locale) {
6 return Lang::get($value, [], $locale);
7 });
8});
9 
10$collection = collect(['first', 'second']);
11 
12$translated = $collection->toLocale('es');
1use Illuminate\Support\Collection;
2use Illuminate\Support\Facades\Lang;
3 
4Collection::macro('toLocale', function ($locale) {
5 return $this->map(function ($value) use ($locale) {
6 return Lang::get($value, [], $locale);
7 });
8});
9 
10$collection = collect(['first', 'second']);
11 
12$translated = $collection->toLocale('es');

可用方法

在 Collection 說明文件剩下的一大部分,我們會討論 Collection 類別內可用的各個方法。請記住,這裡所有的方法都可以互相串接使用,以流利地操作底層的陣列。此外,幾乎所有的函式都會回傳一個新的 Collection 實體,讓你可以在有需要的時候保留原始的 Collection 拷貝:

方法列表

all()

all 方法會回傳該 Collection 所代表的底層陣列:

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

average()

avg 方法的別名。

avg()

avg 方法會回傳給定索引鍵的平均值

1$average = collect([
2 ['foo' => 10],
3 ['foo' => 10],
4 ['foo' => 20],
5 ['foo' => 40]
6])->avg('foo');
7 
8// 20
9 
10$average = collect([1, 1, 2, 4])->avg();
11 
12// 2
1$average = collect([
2 ['foo' => 10],
3 ['foo' => 10],
4 ['foo' => 20],
5 ['foo' => 40]
6])->avg('foo');
7 
8// 20
9 
10$average = collect([1, 1, 2, 4])->avg();
11 
12// 2

chunk()

chunk 方法會將該 Collection 以給定的大小拆分為多個較小的 Collection:

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

此方法特別適合用在 View 內,配合如 Bootstrap 等網格系統一起使用。舉例來說,假設我們有一個 Eloquent 模型的 Collection 想要在網格上顯示:

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

chunkWhile()

chunkWhile 方法會依照給定回呼的取值結果來將 Collection 拆分為多個更小的 Collection。傳入閉包的 $chunk 變數可用來檢視上一個元素:

1$collection = collect(str_split('AABBCCCD'));
2 
3$chunks = $collection->chunkWhile(function ($value, $key, $chunk) {
4 return $value === $chunk->last();
5});
6 
7$chunks->all();
8 
9// [['A', 'A'], ['B', 'B'], ['C', 'C', 'C'], ['D']]
1$collection = collect(str_split('AABBCCCD'));
2 
3$chunks = $collection->chunkWhile(function ($value, $key, $chunk) {
4 return $value === $chunk->last();
5});
6 
7$chunks->all();
8 
9// [['A', 'A'], ['B', 'B'], ['C', 'C', 'C'], ['D']]

collapse()

collapse 方法可以將多個陣列合併為單一的扁平 (Flat) Collection:

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

collect()

collect 方法會回傳一個包含目前 Collection 內項目的新 Collection 實體:

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

collect 方法特別適合用來將 Lazy Collection 轉換為標準 Collection 實體:

1$lazyCollection = LazyCollection::make(function () {
2 yield 1;
3 yield 2;
4 yield 3;
5});
6 
7$collection = $lazyCollection->collect();
8 
9get_class($collection);
10 
11// 'Illuminate\Support\Collection'
12 
13$collection->all();
14 
15// [1, 2, 3]
1$lazyCollection = LazyCollection::make(function () {
2 yield 1;
3 yield 2;
4 yield 3;
5});
6 
7$collection = $lazyCollection->collect();
8 
9get_class($collection);
10 
11// 'Illuminate\Support\Collection'
12 
13$collection->all();
14 
15// [1, 2, 3]
lightbulb

collect 方法特別適合用於如有 Enumerable 實體且需要一個非 Lazy Collection 的實體。由於 collect()Enumerable Contract 的一部分,因此我們可以安全地使用該方法來取得 Collection 實體。

combine()

combine 可用來將 Collection 的值作為索引鍵來與作為值的另一個陣列或 Collection 進行合併:

1$collection = collect(['name', 'age']);
2 
3$combined = $collection->combine(['George', 29]);
4 
5$combined->all();
6 
7// ['name' => 'George', 'age' => 29]
1$collection = collect(['name', 'age']);
2 
3$combined = $collection->combine(['George', 29]);
4 
5$combined->all();
6 
7// ['name' => 'George', 'age' => 29]

concat()

concat 方法會將給定的 array 或 Collection 的值附加到另一個 Collection 的末端:

1$collection = collect(['John Doe']);
2 
3$concatenated = $collection->concat(['Jane Doe'])->concat(['name' => 'Johnny Doe']);
4 
5$concatenated->all();
6 
7// ['John Doe', 'Jane Doe', 'Johnny Doe']
1$collection = collect(['John Doe']);
2 
3$concatenated = $collection->concat(['Jane Doe'])->concat(['name' => 'Johnny Doe']);
4 
5$concatenated->all();
6 
7// ['John Doe', 'Jane Doe', 'Johnny Doe']

concat 方法將各個項目串接到原始 Collection 陣列中,而串接的各個項目會依照數字順序重新設定索引鍵。若要保留關聯式 Collection 的索引鍵,請參照 merge 方法。

contains()

contains 方法可用來判斷該 Collection 是否包含給定的項目。可以傳入一個閉包給 contains 方法來根據給定的真值條件測試判斷某個元素是否在該 Collection 內:

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

或者,也可以將字串傳入 contains 方法來判斷該 Collection 是否包含給定的項目值:

1$collection = collect(['name' => 'Desk', 'price' => 100]);
2 
3$collection->contains('Desk');
4 
5// true
6 
7$collection->contains('New York');
8 
9// false
1$collection = collect(['name' => 'Desk', 'price' => 100]);
2 
3$collection->contains('Desk');
4 
5// true
6 
7$collection->contains('New York');
8 
9// false

也可以傳入一組索引鍵/值配對給 contains 方法,用來判斷給定的索引鍵/值配對是否存在於該 Collection 內:

1$collection = collect([
2 ['product' => 'Desk', 'price' => 200],
3 ['product' => 'Chair', 'price' => 100],
4]);
5 
6$collection->contains('product', 'Bookcase');
7 
8// false
1$collection = collect([
2 ['product' => 'Desk', 'price' => 200],
3 ['product' => 'Chair', 'price' => 100],
4]);
5 
6$collection->contains('product', 'Bookcase');
7 
8// false

contains 方法在比對項目值時使用了「鬆散 (Loose)」的比對方法。這標示,具有整數值的字串與一個有相同值的整數會被視為相同。請使用 containsStrict 方法來使用「嚴格 (Strict)」比對進行過濾。

請參考 doesntContain 方法以瞭解與 contains 相反的方法。

containsOneItem()

containsOneItem 用於判斷該 Collection 是否只包含一個項目:

1collect([])->containsOneItem();
2 
3// false
4 
5collect(['1'])->containsOneItem();
6 
7// true
8 
9collect(['1', '2'])->containsOneItem();
10 
11// false
1collect([])->containsOneItem();
2 
3// false
4 
5collect(['1'])->containsOneItem();
6 
7// true
8 
9collect(['1', '2'])->containsOneItem();
10 
11// false

containsStrict()

該方法與 contains 方法的簽章一致。不過,所有的數值比對都是使用「嚴格」比對模式。

lightbulb

在使用 Eloquent Collection 時,該方法的行為有經過修改。

count()

count 方法回傳該 Collection 內的項目總數:

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

countBy()

countBy 方法會計算在該 Collection 內各個值的出現次數。預設情況下,該方法會計算所有元素的出現次數,讓你可以計算該 Collection 中特定「類型」的元素:

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

可以將一個閉包傳給 countBy 方法來依照自訂值計算所有項目:

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

crossJoin()

The crossJoin method cross joins the collection's values among the given arrays or collections, returning a Cartesian product with all possible permutations:

1$collection = collect([1, 2]);
2 
3$matrix = $collection->crossJoin(['a', 'b']);
4 
5$matrix->all();
6 
7/*
8 [
9 [1, 'a'],
10 [1, 'b'],
11 [2, 'a'],
12 [2, 'b'],
13 ]
14*/
15 
16$collection = collect([1, 2]);
17 
18$matrix = $collection->crossJoin(['a', 'b'], ['I', 'II']);
19 
20$matrix->all();
21 
22/*
23 [
24 [1, 'a', 'I'],
25 [1, 'a', 'II'],
26 [1, 'b', 'I'],
27 [1, 'b', 'II'],
28 [2, 'a', 'I'],
29 [2, 'a', 'II'],
30 [2, 'b', 'I'],
31 [2, 'b', 'II'],
32 ]
33*/
1$collection = collect([1, 2]);
2 
3$matrix = $collection->crossJoin(['a', 'b']);
4 
5$matrix->all();
6 
7/*
8 [
9 [1, 'a'],
10 [1, 'b'],
11 [2, 'a'],
12 [2, 'b'],
13 ]
14*/
15 
16$collection = collect([1, 2]);
17 
18$matrix = $collection->crossJoin(['a', 'b'], ['I', 'II']);
19 
20$matrix->all();
21 
22/*
23 [
24 [1, 'a', 'I'],
25 [1, 'a', 'II'],
26 [1, 'b', 'I'],
27 [1, 'b', 'II'],
28 [2, 'a', 'I'],
29 [2, 'a', 'II'],
30 [2, 'b', 'I'],
31 [2, 'b', 'II'],
32 ]
33*/

dd()

dd 方法會傾印該 Collection 的項目,並結束目前的指令碼執行:

1$collection = collect(['John Doe', 'Jane Doe']);
2 
3$collection->dd();
4 
5/*
6 Collection {
7 #items: array:2 [
8 0 => "John Doe"
9 1 => "Jane Doe"
10 ]
11 }
12*/
1$collection = collect(['John Doe', 'Jane Doe']);
2 
3$collection->dd();
4 
5/*
6 Collection {
7 #items: array:2 [
8 0 => "John Doe"
9 1 => "Jane Doe"
10 ]
11 }
12*/

若不想結束目前的指令碼執行,請改為使用 dump 方法。

diff()

diff 方法會將該 Collection 的值與另一個 Collection 或純 PHP array 陣列進行比對。該方法會回傳在原始 Collection 中有出現,但給定的 Collection 中未出現的值:

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

在使用 Eloquent Collection 時,該方法的行為有經過修改。

diffAssoc()

diffAssoc 方法會將該 Collection 的索引鍵/值與另一個 Collection 或純 PHP array 陣列進行比對。該方法會回傳在原始 Collection 中有出現,但給定的 Collection 中未出現的索引鍵/值配對:

1$collection = collect([
2 'color' => 'orange',
3 'type' => 'fruit',
4 'remain' => 6,
5]);
6 
7$diff = $collection->diffAssoc([
8 'color' => 'yellow',
9 'type' => 'fruit',
10 'remain' => 3,
11 'used' => 6,
12]);
13 
14$diff->all();
15 
16// ['color' => 'orange', 'remain' => 6]
1$collection = collect([
2 'color' => 'orange',
3 'type' => 'fruit',
4 'remain' => 6,
5]);
6 
7$diff = $collection->diffAssoc([
8 'color' => 'yellow',
9 'type' => 'fruit',
10 'remain' => 3,
11 'used' => 6,
12]);
13 
14$diff->all();
15 
16// ['color' => 'orange', 'remain' => 6]

diffKeys()

diffKey 方法會將該 Collection 的索引鍵與另一個 Collection 或純 PHP array 陣列進行比對。該方法會回傳在原始 Collection 中有出現,但給定的 Collection 中未出現的索引對:

1$collection = collect([
2 'one' => 10,
3 'two' => 20,
4 'three' => 30,
5 'four' => 40,
6 'five' => 50,
7]);
8 
9$diff = $collection->diffKeys([
10 'two' => 2,
11 'four' => 4,
12 'six' => 6,
13 'eight' => 8,
14]);
15 
16$diff->all();
17 
18// ['one' => 10, 'three' => 30, 'five' => 50]
1$collection = collect([
2 'one' => 10,
3 'two' => 20,
4 'three' => 30,
5 'four' => 40,
6 'five' => 50,
7]);
8 
9$diff = $collection->diffKeys([
10 'two' => 2,
11 'four' => 4,
12 'six' => 6,
13 'eight' => 8,
14]);
15 
16$diff->all();
17 
18// ['one' => 10, 'three' => 30, 'five' => 50]

doesntContain()

doesntContain 方法可用來判斷該 Collection 是否不包含給定的項目。可以傳入一個閉包給 doesntContain 方法來根據給定的真值條件測試判斷某個元素是否不在該 Collection 內:

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

或者,也可以將字串傳入 doesntContain 方法來判斷該 Collection 是否不包含給定的項目值:

1$collection = collect(['name' => 'Desk', 'price' => 100]);
2 
3$collection->doesntContain('Table');
4 
5// true
6 
7$collection->doesntContain('Desk');
8 
9// false
1$collection = collect(['name' => 'Desk', 'price' => 100]);
2 
3$collection->doesntContain('Table');
4 
5// true
6 
7$collection->doesntContain('Desk');
8 
9// false

也可以傳入一組索引鍵/值配對給 doesntContains 方法,用來判斷給定的索引鍵/值配對是否不存在於該 Collection 內:

1$collection = collect([
2 ['product' => 'Desk', 'price' => 200],
3 ['product' => 'Chair', 'price' => 100],
4]);
5 
6$collection->doesntContain('product', 'Bookcase');
7 
8// true
1$collection = collect([
2 ['product' => 'Desk', 'price' => 200],
3 ['product' => 'Chair', 'price' => 100],
4]);
5 
6$collection->doesntContain('product', 'Bookcase');
7 
8// true

doesntContain 方法在比對項目值時使用了「鬆散 (Loose)」的比對方法。這表示,具有整數值的字串與一個有相同值的整數會被視為相同。

dump()

dump 方法會傾印出該 Collection 中的項目:

1$collection = collect(['John Doe', 'Jane Doe']);
2 
3$collection->dump();
4 
5/*
6 Collection {
7 #items: array:2 [
8 0 => "John Doe"
9 1 => "Jane Doe"
10 ]
11 }
12*/
1$collection = collect(['John Doe', 'Jane Doe']);
2 
3$collection->dump();
4 
5/*
6 Collection {
7 #items: array:2 [
8 0 => "John Doe"
9 1 => "Jane Doe"
10 ]
11 }
12*/

若想在傾印該 Collection 後停止執行指令碼,請使用 dd 方法來代替。

duplicates()

duplicates 方法會取得並回傳該 Collection 中重複的值:

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

若該 Collection 內包含陣列或物件,則可以傳入想用來檢查重複值的屬性索引鍵:

1$employees = collect([
2 ['email' => '[email protected]', 'position' => 'Developer'],
3 ['email' => '[email protected]', 'position' => 'Designer'],
4 ['email' => '[email protected]', 'position' => 'Developer'],
5]);
6 
7$employees->duplicates('position');
8 
9// [2 => 'Developer']
1$employees = collect([
2 ['email' => '[email protected]', 'position' => 'Developer'],
3 ['email' => '[email protected]', 'position' => 'Designer'],
4 ['email' => '[email protected]', 'position' => 'Developer'],
5]);
6 
7$employees->duplicates('position');
8 
9// [2 => 'Developer']

duplicatesStrict()

該方法與 duplicates 方法的簽章一致。不過,所有的數值比對都是使用「嚴格」比對模式。

each()

each 方法會迭代 Collection 中的項目,並將各個項目傳給閉包:

1$collection->each(function ($item, $key) {
2 //
3});
1$collection->each(function ($item, $key) {
2 //
3});

若想停止迭代項目,可以在閉包內回傳 false

1$collection->each(function ($item, $key) {
2 if (/* condition */) {
3 return false;
4 }
5});
1$collection->each(function ($item, $key) {
2 if (/* condition */) {
3 return false;
4 }
5});

eachSpread()

eachSpread 方法會迭代該 Collection 的項目,並將每個巢狀項目傳入給定的回呼:

1$collection = collect([['John Doe', 35], ['Jane Doe', 33]]);
2 
3$collection->eachSpread(function ($name, $age) {
4 //
5});
1$collection = collect([['John Doe', 35], ['Jane Doe', 33]]);
2 
3$collection->eachSpread(function ($name, $age) {
4 //
5});

可以通過在回呼內回傳 false 來停止迭代項目:

1$collection->eachSpread(function ($name, $age) {
2 return false;
3});
1$collection->eachSpread(function ($name, $age) {
2 return false;
3});

every()

every 方法可以用來認證某個 Collection 中的所有元素是否都通過了給定的布林測試:

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

若 Collection 為空,則 every 方法總是回傳 true:

1$collection = collect([]);
2 
3$collection->every(function ($value, $key) {
4 return $value > 2;
5});
6 
7// true
1$collection = collect([]);
2 
3$collection->every(function ($value, $key) {
4 return $value > 2;
5});
6 
7// true

except()

except 方法會回傳該 Collection 中,除了具有特定索引鍵外的所有項目:

1$collection = collect(['product_id' => 1, 'price' => 100, 'discount' => false]);
2 
3$filtered = $collection->except(['price', 'discount']);
4 
5$filtered->all();
6 
7// ['product_id' => 1]
1$collection = collect(['product_id' => 1, 'price' => 100, 'discount' => false]);
2 
3$filtered = $collection->except(['price', 'discount']);
4 
5$filtered->all();
6 
7// ['product_id' => 1]

請參考 only 方法以瞭解與 except 相反的方法。

lightbulb

在使用 Eloquent Collection 時,該方法的行為有經過修改。

filter()

filter 方法會使用給定的回呼來篩選該 Collection,並只保留通過給定布林測試的項目:

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

若未提供回呼,則該 Collection 中所有等價於 false 的項目都會被移除:

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

請參考 reject 方法以瞭解與 filter 相反的方法。

first()

first 方法會回傳該 Collection 中通過給定布林測試的第一個元素:

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

呼叫 first 方法時也可以不給任何引數,以取得該 Collection 中的第一個元素。若該 Collection 為空,則會回傳 null

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

firstOrFail()

firstOrFail 方法與 first 方法完全相同。不過,若無結果,則會擲回 Illuminate\Support\ItemNotFoundException Exception:

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

我們也可以不帶任何參數地呼叫 firstOrFail 方法,以取得該 Collection 中的第一個元素。若該 Collection 為空,則會擲回 Illuminate\Support\ItemNotFoundException Exception:

1collect([])->firstOrFail();
2 
3// 擲回 ItemNotFoundException...
1collect([])->firstOrFail();
2 
3// 擲回 ItemNotFoundException...

firstWhere()

firstWhere 方法會回傳該 Collection 中具有給定索引鍵/值配對的第一個元素:

1$collection = collect([
2 ['name' => 'Regena', 'age' => null],
3 ['name' => 'Linda', 'age' => 14],
4 ['name' => 'Diego', 'age' => 23],
5 ['name' => 'Linda', 'age' => 84],
6]);
7 
8$collection->firstWhere('name', 'Linda');
9 
10// ['name' => 'Linda', 'age' => 14]
1$collection = collect([
2 ['name' => 'Regena', 'age' => null],
3 ['name' => 'Linda', 'age' => 14],
4 ['name' => 'Diego', 'age' => 23],
5 ['name' => 'Linda', 'age' => 84],
6]);
7 
8$collection->firstWhere('name', 'Linda');
9 
10// ['name' => 'Linda', 'age' => 14]

也可以使用比較運算子來呼叫 firstWhere 方法:

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

where 方法類似,可以傳入一個引數給 firstWhere 方法。在這種情境下,firstWhere 方法會回傳給定項目的索引鍵值可被視為「True」的第一個項目:

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

flatMap()

flatMap 方法會迭代該 Collection,並將每個值傳入給定的閉包。該閉包可自由修改項目並進行回傳,藉此依據修改的項目來建立一個新的 Collection。接著,陣列會被扁平化一個階層:

1$collection = collect([
2 ['name' => 'Sally'],
3 ['school' => 'Arkansas'],
4 ['age' => 28]
5]);
6 
7$flattened = $collection->flatMap(function ($values) {
8 return array_map('strtoupper', $values);
9});
10 
11$flattened->all();
12 
13// ['name' => 'SALLY', 'school' => 'ARKANSAS', 'age' => '28'];
1$collection = collect([
2 ['name' => 'Sally'],
3 ['school' => 'Arkansas'],
4 ['age' => 28]
5]);
6 
7$flattened = $collection->flatMap(function ($values) {
8 return array_map('strtoupper', $values);
9});
10 
11$flattened->all();
12 
13// ['name' => 'SALLY', 'school' => 'ARKANSAS', 'age' => '28'];

flatten()

flatten 方法會將一個多維 Collection 扁平化為單一維度:

1$collection = collect([
2 'name' => 'taylor',
3 'languages' => [
4 'php', 'javascript'
5 ]
6]);
7 
8$flattened = $collection->flatten();
9 
10$flattened->all();
11 
12// ['taylor', 'php', 'javascript'];
1$collection = collect([
2 'name' => 'taylor',
3 'languages' => [
4 'php', 'javascript'
5 ]
6]);
7 
8$flattened = $collection->flatten();
9 
10$flattened->all();
11 
12// ['taylor', 'php', 'javascript'];

若有需要,可以傳入一個可選的「depth 深度」引數:

1$collection = collect([
2 'Apple' => [
3 [
4 'name' => 'iPhone 6S',
5 'brand' => 'Apple'
6 ],
7 ],
8 'Samsung' => [
9 [
10 'name' => 'Galaxy S7',
11 'brand' => 'Samsung'
12 ],
13 ],
14]);
15 
16$products = $collection->flatten(1);
17 
18$products->values()->all();
19 
20/*
21 [
22 ['name' => 'iPhone 6S', 'brand' => 'Apple'],
23 ['name' => 'Galaxy S7', 'brand' => 'Samsung'],
24 ]
25*/
1$collection = collect([
2 'Apple' => [
3 [
4 'name' => 'iPhone 6S',
5 'brand' => 'Apple'
6 ],
7 ],
8 'Samsung' => [
9 [
10 'name' => 'Galaxy S7',
11 'brand' => 'Samsung'
12 ],
13 ],
14]);
15 
16$products = $collection->flatten(1);
17 
18$products->values()->all();
19 
20/*
21 [
22 ['name' => 'iPhone 6S', 'brand' => 'Apple'],
23 ['name' => 'Galaxy S7', 'brand' => 'Samsung'],
24 ]
25*/

在此範例中,在不提供深度的情況下呼叫 flatten 會連巢狀陣列也一併被扁平化,產生 ['iPhone 6S', 'Apple', 'Galaxy S7', 'Samsung']。若提供了深度,則可指定哪些等級的巢狀陣列要被扁平化。

flip()

flip 方法會將該 Collection 的索引鍵與其對應的值進行呼喚:

1$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
2 
3$flipped = $collection->flip();
4 
5$flipped->all();
6 
7// ['taylor' => 'name', 'laravel' => 'framework']
1$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
2 
3$flipped = $collection->flip();
4 
5$flipped->all();
6 
7// ['taylor' => 'name', 'laravel' => 'framework']

forget()

forget 方法根據項目的索引鍵來在該 Collection 中移除項目:

1$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
2 
3$collection->forget('name');
4 
5$collection->all();
6 
7// ['framework' => 'laravel']
1$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
2 
3$collection->forget('name');
4 
5$collection->all();
6 
7// ['framework' => 'laravel']
exclamation

與其他大多數 Collection 方法不同,forget 不會回傳經過修改的新 Collection。該方法會修改被呼叫的那個 Collection。

forPage()

forPage 會回傳一個新的 Collection,包含指定頁碼上的項目。該方法接受第一個引數為頁碼,而第二個引數則為每頁要顯示幾個項目:

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

get()

get 方法會回傳給定索引鍵上的項目。若該索引鍵不存在,則會回傳 null

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

也可以傳入可選的第二個引數提供預設值:

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

也可以傳入一個回呼來作為該方法的預設值。若特定的索引鍵不存在,就會回傳該回呼的結果:

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

groupBy()

groupBy 方法會依照給定的索引鍵來將該 Collection 的項目分組:

1$collection = collect([
2 ['account_id' => 'account-x10', 'product' => 'Chair'],
3 ['account_id' => 'account-x10', 'product' => 'Bookcase'],
4 ['account_id' => 'account-x11', 'product' => 'Desk'],
5]);
6 
7$grouped = $collection->groupBy('account_id');
8 
9$grouped->all();
10 
11/*
12 [
13 'account-x10' => [
14 ['account_id' => 'account-x10', 'product' => 'Chair'],
15 ['account_id' => 'account-x10', 'product' => 'Bookcase'],
16 ],
17 'account-x11' => [
18 ['account_id' => 'account-x11', 'product' => 'Desk'],
19 ],
20 ]
21*/
1$collection = collect([
2 ['account_id' => 'account-x10', 'product' => 'Chair'],
3 ['account_id' => 'account-x10', 'product' => 'Bookcase'],
4 ['account_id' => 'account-x11', 'product' => 'Desk'],
5]);
6 
7$grouped = $collection->groupBy('account_id');
8 
9$grouped->all();
10 
11/*
12 [
13 'account-x10' => [
14 ['account_id' => 'account-x10', 'product' => 'Chair'],
15 ['account_id' => 'account-x10', 'product' => 'Bookcase'],
16 ],
17 'account-x11' => [
18 ['account_id' => 'account-x11', 'product' => 'Desk'],
19 ],
20 ]
21*/

除了傳入字串 key 以外,也可以傳入一個回呼。該回呼應回傳用於分組的索引鍵值:

1$grouped = $collection->groupBy(function ($item, $key) {
2 return substr($item['account_id'], -3);
3});
4 
5$grouped->all();
6 
7/*
8 [
9 'x10' => [
10 ['account_id' => 'account-x10', 'product' => 'Chair'],
11 ['account_id' => 'account-x10', 'product' => 'Bookcase'],
12 ],
13 'x11' => [
14 ['account_id' => 'account-x11', 'product' => 'Desk'],
15 ],
16 ]
17*/
1$grouped = $collection->groupBy(function ($item, $key) {
2 return substr($item['account_id'], -3);
3});
4 
5$grouped->all();
6 
7/*
8 [
9 'x10' => [
10 ['account_id' => 'account-x10', 'product' => 'Chair'],
11 ['account_id' => 'account-x10', 'product' => 'Bookcase'],
12 ],
13 'x11' => [
14 ['account_id' => 'account-x11', 'product' => 'Desk'],
15 ],
16 ]
17*/

若有多個分組的方法,則可傳入陣列。陣列中的各個元素會被在對應的多維陣列上的層級:

1$data = new Collection([
2 10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
3 20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
4 30 => ['user' => 3, 'skill' => 2, 'roles' => ['Role_1']],
5 40 => ['user' => 4, 'skill' => 2, 'roles' => ['Role_2']],
6]);
7 
8$result = $data->groupBy(['skill', function ($item) {
9 return $item['roles'];
10}], preserveKeys: true);
11 
12/*
13[
14 1 => [
15 'Role_1' => [
16 10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
17 20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
18 ],
19 'Role_2' => [
20 20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
21 ],
22 'Role_3' => [
23 10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
24 ],
25 ],
26 2 => [
27 'Role_1' => [
28 30 => ['user' => 3, 'skill' => 2, 'roles' => ['Role_1']],
29 ],
30 'Role_2' => [
31 40 => ['user' => 4, 'skill' => 2, 'roles' => ['Role_2']],
32 ],
33 ],
34];
35*/
1$data = new Collection([
2 10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
3 20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
4 30 => ['user' => 3, 'skill' => 2, 'roles' => ['Role_1']],
5 40 => ['user' => 4, 'skill' => 2, 'roles' => ['Role_2']],
6]);
7 
8$result = $data->groupBy(['skill', function ($item) {
9 return $item['roles'];
10}], preserveKeys: true);
11 
12/*
13[
14 1 => [
15 'Role_1' => [
16 10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
17 20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
18 ],
19 'Role_2' => [
20 20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
21 ],
22 'Role_3' => [
23 10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
24 ],
25 ],
26 2 => [
27 'Role_1' => [
28 30 => ['user' => 3, 'skill' => 2, 'roles' => ['Role_1']],
29 ],
30 'Role_2' => [
31 40 => ['user' => 4, 'skill' => 2, 'roles' => ['Role_2']],
32 ],
33 ],
34];
35*/

has()

has 方法用於判斷給定的索引鍵是否存在於該 Collection 上:

1$collection = collect(['account_id' => 1, 'product' => 'Desk', 'amount' => 5]);
2 
3$collection->has('product');
4 
5// true
6 
7$collection->has(['product', 'amount']);
8 
9// true
10 
11$collection->has(['amount', 'price']);
12 
13// false
1$collection = collect(['account_id' => 1, 'product' => 'Desk', 'amount' => 5]);
2 
3$collection->has('product');
4 
5// true
6 
7$collection->has(['product', 'amount']);
8 
9// true
10 
11$collection->has(['amount', 'price']);
12 
13// false

hasAny()

hasAny 方法用於判斷給定的多個索引鍵中,是否有任何索引鍵存在於該 Collection 上:

1$collection = collect(['account_id' => 1, 'product' => 'Desk', 'amount' => 5]);
2 
3$collection->hasAny(['product', 'price']);
4 
5// true
6 
7$collection->hasAny(['name', 'price']);
8 
9// false
1$collection = collect(['account_id' => 1, 'product' => 'Desk', 'amount' => 5]);
2 
3$collection->hasAny(['product', 'price']);
4 
5// true
6 
7$collection->hasAny(['name', 'price']);
8 
9// false

implode()

implode 方法可將 Collection 內多個項目串聯。該方法的引數會依照該 Collection 中項目的類型而有所不同。若該 Collection 中包含陣列或物件,則應傳入欲串聯的屬性之索引鍵,以及要用來串聯各個值的「Glue (黏著)」字串:

1$collection = collect([
2 ['account_id' => 1, 'product' => 'Desk'],
3 ['account_id' => 2, 'product' => 'Chair'],
4]);
5 
6$collection->implode('product', ', ');
7 
8// Desk, Chair
1$collection = collect([
2 ['account_id' => 1, 'product' => 'Desk'],
3 ['account_id' => 2, 'product' => 'Chair'],
4]);
5 
6$collection->implode('product', ', ');
7 
8// Desk, Chair

若該 Collection 中只包含了單純的字串或數字值,則只需要傳入「Glue (黏著)」字串作為該方法唯一的引數即可:

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

若想為 implode 後的值自定格式,可以傳入一個閉包給 implode 方法:

1$collection->implode(function ($item, $key) {
2 return strtoupper($item['product']);
3}, ', ');
4 
5// DESK, CHAIR
1$collection->implode(function ($item, $key) {
2 return strtoupper($item['product']);
3}, ', ');
4 
5// DESK, CHAIR

intersect()

intersect 方法會從原始 Collection 中移除給定 array 或 Collection 中不存在的值。產生的 Collection 會保有原始 Collection 的索引鍵:

1$collection = collect(['Desk', 'Sofa', 'Chair']);
2 
3$intersect = $collection->intersect(['Desk', 'Chair', 'Bookcase']);
4 
5$intersect->all();
6 
7// [0 => 'Desk', 2 => 'Chair']
1$collection = collect(['Desk', 'Sofa', 'Chair']);
2 
3$intersect = $collection->intersect(['Desk', 'Chair', 'Bookcase']);
4 
5$intersect->all();
6 
7// [0 => 'Desk', 2 => 'Chair']
lightbulb

在使用 Eloquent Collection 時,該方法的行為有經過修改。

intersectByKeys()

intersectByKeys 方法會自原始 Collection 中移除其索引鍵不存在於給定 array 或 Collection 中的索引鍵與值:

1$collection = collect([
2 'serial' => 'UX301', 'type' => 'screen', 'year' => 2009,
3]);
4 
5$intersect = $collection->intersectByKeys([
6 'reference' => 'UX404', 'type' => 'tab', 'year' => 2011,
7]);
8 
9$intersect->all();
10 
11// ['type' => 'screen', 'year' => 2009]
1$collection = collect([
2 'serial' => 'UX301', 'type' => 'screen', 'year' => 2009,
3]);
4 
5$intersect = $collection->intersectByKeys([
6 'reference' => 'UX404', 'type' => 'tab', 'year' => 2011,
7]);
8 
9$intersect->all();
10 
11// ['type' => 'screen', 'year' => 2009]

isEmpty()

isEmpty 會在該 Collection 為空時回傳 true。否則會回傳 false

1collect([])->isEmpty();
2 
3// true
1collect([])->isEmpty();
2 
3// true

isNotEmpty()

isNotEmpty 會在該 Collection 不為空時回傳 true。否則會回傳 false

1collect([])->isNotEmpty();
2 
3// false
1collect([])->isNotEmpty();
2 
3// false

join()

join 方法會將該 Collection 中的值合併為一個字串。使用該方法的第二個引數可用來指定最後一個元素要如何被加進字串裡:

1collect(['a', 'b', 'c'])->join(', '); // 'a, b, c'
2collect(['a', 'b', 'c'])->join(', ', ', and '); // 'a, b, and c'
3collect(['a', 'b'])->join(', ', ' and '); // 'a and b'
4collect(['a'])->join(', ', ' and '); // 'a'
5collect([])->join(', ', ' and '); // ''
1collect(['a', 'b', 'c'])->join(', '); // 'a, b, c'
2collect(['a', 'b', 'c'])->join(', ', ', and '); // 'a, b, and c'
3collect(['a', 'b'])->join(', ', ' and '); // 'a and b'
4collect(['a'])->join(', ', ' and '); // 'a'
5collect([])->join(', ', ' and '); // ''

keyBy()

keyBy 方法依照給定的索引鍵來將該 Collection 加上索引鍵。若多個項目有相同的索引鍵,則新的 Collection 中只會包含最後一個項目:

1$collection = collect([
2 ['product_id' => 'prod-100', 'name' => 'Desk'],
3 ['product_id' => 'prod-200', 'name' => 'Chair'],
4]);
5 
6$keyed = $collection->keyBy('product_id');
7 
8$keyed->all();
9 
10/*
11 [
12 'prod-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
13 'prod-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
14 ]
15*/
1$collection = collect([
2 ['product_id' => 'prod-100', 'name' => 'Desk'],
3 ['product_id' => 'prod-200', 'name' => 'Chair'],
4]);
5 
6$keyed = $collection->keyBy('product_id');
7 
8$keyed->all();
9 
10/*
11 [
12 'prod-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
13 'prod-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
14 ]
15*/

也可以傳入回呼給該方法。該回呼應回傳用於為該 Collection 加上索引鍵的值:

1$keyed = $collection->keyBy(function ($item, $key) {
2 return strtoupper($item['product_id']);
3});
4 
5$keyed->all();
6 
7/*
8 [
9 'PROD-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
10 'PROD-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
11 ]
12*/
1$keyed = $collection->keyBy(function ($item, $key) {
2 return strtoupper($item['product_id']);
3});
4 
5$keyed->all();
6 
7/*
8 [
9 'PROD-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
10 'PROD-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
11 ]
12*/

keys()

keys 方法回傳該 Collection 中的所有索引鍵:

1$collection = collect([
2 'prod-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
3 'prod-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
4]);
5 
6$keys = $collection->keys();
7 
8$keys->all();
9 
10// ['prod-100', 'prod-200']
1$collection = collect([
2 'prod-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
3 'prod-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
4]);
5 
6$keys = $collection->keys();
7 
8$keys->all();
9 
10// ['prod-100', 'prod-200']

last()

last 方法會回傳該 Collection 中通過給定布林測試的最後一個元素:

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

呼叫 last 方法時也可以不給任何引數,以取得該 Collection 中的最後一個元素。若該 Collection 為空,則會回傳 null

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

lazy()

lazy 方法使用底層項目陣列來回傳一個新的 LazyCollection 實體:

1$lazyCollection = collect([1, 2, 3, 4])->lazy();
2 
3get_class($lazyCollection);
4 
5// Illuminate\Support\LazyCollection
6 
7$lazyCollection->all();
8 
9// [1, 2, 3, 4]
1$lazyCollection = collect([1, 2, 3, 4])->lazy();
2 
3get_class($lazyCollection);
4 
5// Illuminate\Support\LazyCollection
6 
7$lazyCollection->all();
8 
9// [1, 2, 3, 4]

若想轉換一個有許多項目的大型 Collection,就特別適合使用該方法:

1$count = $hugeCollection
2 ->lazy()
3 ->where('country', 'FR')
4 ->where('balance', '>', '100')
5 ->count();
1$count = $hugeCollection
2 ->lazy()
3 ->where('country', 'FR')
4 ->where('balance', '>', '100')
5 ->count();

將 Collection 轉為 LazyCollection 後,就可避免使用到大量額外的記憶體。雖然,原始陣列的值 還是會保存在記憶體中,但之後所進行的篩選結果將不會被保存在記憶體中。因此,在篩選 Collection 結果時,將不會使用到額外的記憶體。

macro()

靜態 macro 方法可用來在執行階段將方法加入 Collection 類別內。更多資訊請參考有關擴充 Collection 的說明文件。

make()

The static make method creates a new collection instance. See the Creating Collections section.

map()

map 方法會迭代該 Collection,並將每個值傳入給定的回呼。該回呼可自由修改項目並進行回傳,藉此依據修改的項目來建立一個新的 Collection:

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

與其他 Collection 方法類似,map 會回傳一個新的 Collection 實體。該方法不會修改正在呼叫的 Collection。若想改變原始 Collection,請使用 transform 方法代替。

mapInto()

The mapInto() method iterates over the collection, creating a new instance of the given class by passing the value into the constructor:

1class Currency
2{
3 /**
4 * Create a new currency instance.
5 *
6 * @param string $code
7 * @return void
8 */
9 function __construct(string $code)
10 {
11 $this->code = $code;
12 }
13}
14 
15$collection = collect(['USD', 'EUR', 'GBP']);
16 
17$currencies = $collection->mapInto(Currency::class);
18 
19$currencies->all();
20 
21// [Currency('USD'), Currency('EUR'), Currency('GBP')]
1class Currency
2{
3 /**
4 * Create a new currency instance.
5 *
6 * @param string $code
7 * @return void
8 */
9 function __construct(string $code)
10 {
11 $this->code = $code;
12 }
13}
14 
15$collection = collect(['USD', 'EUR', 'GBP']);
16 
17$currencies = $collection->mapInto(Currency::class);
18 
19$currencies->all();
20 
21// [Currency('USD'), Currency('EUR'), Currency('GBP')]

mapSpread()

mapSpread 方法會迭代該 Collection 的項目,並將各個巢狀項目傳入給定的閉包內。該閉包可修改這些項目並回傳,藉此以修改過的項目來建立新的 Collection:

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

mapToGroups()

mapToGroups 方法使用給定的閉包來分組該 Collection 的項目。該閉包應回傳一個包含單一索引鍵/值配對的關聯性陣列,藉此以經過分組的值來建立新的 Collection:

1$collection = collect([
2 [
3 'name' => 'John Doe',
4 'department' => 'Sales',
5 ],
6 [
7 'name' => 'Jane Doe',
8 'department' => 'Sales',
9 ],
10 [
11 'name' => 'Johnny Doe',
12 'department' => 'Marketing',
13 ]
14]);
15 
16$grouped = $collection->mapToGroups(function ($item, $key) {
17 return [$item['department'] => $item['name']];
18});
19 
20$grouped->all();
21 
22/*
23 [
24 'Sales' => ['John Doe', 'Jane Doe'],
25 'Marketing' => ['Johnny Doe'],
26 ]
27*/
28 
29$grouped->get('Sales')->all();
30 
31// ['John Doe', 'Jane Doe']
1$collection = collect([
2 [
3 'name' => 'John Doe',
4 'department' => 'Sales',
5 ],
6 [
7 'name' => 'Jane Doe',
8 'department' => 'Sales',
9 ],
10 [
11 'name' => 'Johnny Doe',
12 'department' => 'Marketing',
13 ]
14]);
15 
16$grouped = $collection->mapToGroups(function ($item, $key) {
17 return [$item['department'] => $item['name']];
18});
19 
20$grouped->all();
21 
22/*
23 [
24 'Sales' => ['John Doe', 'Jane Doe'],
25 'Marketing' => ['Johnny Doe'],
26 ]
27*/
28 
29$grouped->get('Sales')->all();
30 
31// ['John Doe', 'Jane Doe']

mapWithKeys()

mapWithKeys 方法會迭代該 Collection,並將各個值傳入給定的回呼。該回呼應回傳一個包含單一索引鍵/值配對的關聯性陣列:

1$collection = collect([
2 [
3 'name' => 'John',
4 'department' => 'Sales',
5 'email' => '[email protected]',
6 ],
7 [
8 'name' => 'Jane',
9 'department' => 'Marketing',
10 'email' => '[email protected]',
11 ]
12]);
13 
14$keyed = $collection->mapWithKeys(function ($item, $key) {
15 return [$item['email'] => $item['name']];
16});
17 
18$keyed->all();
19 
20/*
21 [
22 '[email protected]' => 'John',
23 '[email protected]' => 'Jane',
24 ]
25*/
1$collection = collect([
2 [
3 'name' => 'John',
4 'department' => 'Sales',
5 'email' => '[email protected]',
6 ],
7 [
8 'name' => 'Jane',
9 'department' => 'Marketing',
10 'email' => '[email protected]',
11 ]
12]);
13 
14$keyed = $collection->mapWithKeys(function ($item, $key) {
15 return [$item['email'] => $item['name']];
16});
17 
18$keyed->all();
19 
20/*
21 [
22 '[email protected]' => 'John',
23 '[email protected]' => 'Jane',
24 ]
25*/

max()

max 方法回傳給定索引鍵的最大值:

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

median()

medium 方法會回傳給定索引鍵的中位數

1$median = collect([
2 ['foo' => 10],
3 ['foo' => 10],
4 ['foo' => 20],
5 ['foo' => 40]
6])->median('foo');
7 
8// 15
9 
10$median = collect([1, 1, 2, 4])->median();
11 
12// 1.5
1$median = collect([
2 ['foo' => 10],
3 ['foo' => 10],
4 ['foo' => 20],
5 ['foo' => 40]
6])->median('foo');
7 
8// 15
9 
10$median = collect([1, 1, 2, 4])->median();
11 
12// 1.5

merge()

merge 方法會將給定的陣列或 Collection 與原始 Collection 合併。若在給定項目中有字串索引鍵與原始 Collection 中的字串索引鍵相同,則給定項目的值會覆蓋原始 Collection 中的值:

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

若給定項目的索引鍵是數字值,則其值會被加到該 Collection 的最後面:

1$collection = collect(['Desk', 'Chair']);
2 
3$merged = $collection->merge(['Bookcase', 'Door']);
4 
5$merged->all();
6 
7// ['Desk', 'Chair', 'Bookcase', 'Door']
1$collection = collect(['Desk', 'Chair']);
2 
3$merged = $collection->merge(['Bookcase', 'Door']);
4 
5$merged->all();
6 
7// ['Desk', 'Chair', 'Bookcase', 'Door']

mergeRecursive()

mergeRecursive 方法會將給定的陣列或 Collection 與原始 Collection 遞迴合併。若在給定項目中有字串索引鍵與原始 Collection 中的字串索引鍵相同,則這些索引鍵的值將被一起合併為一個陣列,且此一過程將遞迴進行:

1$collection = collect(['product_id' => 1, 'price' => 100]);
2 
3$merged = $collection->mergeRecursive([
4 'product_id' => 2,
5 'price' => 200,
6 'discount' => false
7]);
8 
9$merged->all();
10 
11// ['product_id' => [1, 2], 'price' => [100, 200], 'discount' => false]
1$collection = collect(['product_id' => 1, 'price' => 100]);
2 
3$merged = $collection->mergeRecursive([
4 'product_id' => 2,
5 'price' => 200,
6 'discount' => false
7]);
8 
9$merged->all();
10 
11// ['product_id' => [1, 2], 'price' => [100, 200], 'discount' => false]

min()

min 方法回傳給定索引鍵的最小值:

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

mode()

mode 方法會回傳給定索引鍵的眾數

1$mode = collect([
2 ['foo' => 10],
3 ['foo' => 10],
4 ['foo' => 20],
5 ['foo' => 40]
6])->mode('foo');
7 
8// [10]
9 
10$mode = collect([1, 1, 2, 4])->mode();
11 
12// [1]
13 
14$mode = collect([1, 1, 2, 2])->mode();
15 
16// [1, 2]
1$mode = collect([
2 ['foo' => 10],
3 ['foo' => 10],
4 ['foo' => 20],
5 ['foo' => 40]
6])->mode('foo');
7 
8// [10]
9 
10$mode = collect([1, 1, 2, 4])->mode();
11 
12// [1]
13 
14$mode = collect([1, 1, 2, 2])->mode();
15 
16// [1, 2]

nth()

nth 方法會使用每 n 個元素來建立新的 Collection:

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

也可以傳入可選的第二個引數來設定起始偏移值:

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

only()

only 方法會回傳該 Collection 中具有特定索引鍵的所有項目:

1$collection = collect([
2 'product_id' => 1,
3 'name' => 'Desk',
4 'price' => 100,
5 'discount' => false
6]);
7 
8$filtered = $collection->only(['product_id', 'name']);
9 
10$filtered->all();
11 
12// ['product_id' => 1, 'name' => 'Desk']
1$collection = collect([
2 'product_id' => 1,
3 'name' => 'Desk',
4 'price' => 100,
5 'discount' => false
6]);
7 
8$filtered = $collection->only(['product_id', 'name']);
9 
10$filtered->all();
11 
12// ['product_id' => 1, 'name' => 'Desk']

請參考 except 方法以瞭解與 only 相反的方法。

lightbulb

在使用 Eloquent Collection 時,該方法的行為有經過修改。

pad()

pad 方法會以給定的值來填充陣列,直到該陣列達到特定大小。該方法的行為與 array_pad PHP 方法類似。

若要向左填充,則可指定負數大小。若給定大小的絕對值小於或等於該陣列的長度,則不會進行填充:

1$collection = collect(['A', 'B', 'C']);
2 
3$filtered = $collection->pad(5, 0);
4 
5$filtered->all();
6 
7// ['A', 'B', 'C', 0, 0]
8 
9$filtered = $collection->pad(-5, 0);
10 
11$filtered->all();
12 
13// [0, 0, 'A', 'B', 'C']
1$collection = collect(['A', 'B', 'C']);
2 
3$filtered = $collection->pad(5, 0);
4 
5$filtered->all();
6 
7// ['A', 'B', 'C', 0, 0]
8 
9$filtered = $collection->pad(-5, 0);
10 
11$filtered->all();
12 
13// [0, 0, 'A', 'B', 'C']

partition()

partition 方法可用來與 PHP 的陣列結構函式一起使用,以區分出符合與不符合給定布林測試的元素:

1$collection = collect([1, 2, 3, 4, 5, 6]);
2 
3[$underThree, $equalOrAboveThree] = $collection->partition(function ($i) {
4 return $i < 3;
5});
6 
7$underThree->all();
8 
9// [1, 2]
10 
11$equalOrAboveThree->all();
12 
13// [3, 4, 5, 6]
1$collection = collect([1, 2, 3, 4, 5, 6]);
2 
3[$underThree, $equalOrAboveThree] = $collection->partition(function ($i) {
4 return $i < 3;
5});
6 
7$underThree->all();
8 
9// [1, 2]
10 
11$equalOrAboveThree->all();
12 
13// [3, 4, 5, 6]

pipe()

pipe 方法會將該 Collection 傳入給定閉包,並回傳執行該閉包的結果:

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

pipeInto()

pipeInto 方法會以給定的類別建立新實體,並將該 Collection 傳入其建構函式內:

1class ResourceCollection
2{
3 /**
4 * The Collection instance.
5 */
6 public $collection;
7 
8 /**
9 * Create a new ResourceCollection instance.
10 *
11 * @param Collection $collection
12 * @return void
13 */
14 public function __construct(Collection $collection)
15 {
16 $this->collection = $collection;
17 }
18}
19 
20$collection = collect([1, 2, 3]);
21 
22$resource = $collection->pipeInto(ResourceCollection::class);
23 
24$resource->collection->all();
25 
26// [1, 2, 3]
1class ResourceCollection
2{
3 /**
4 * The Collection instance.
5 */
6 public $collection;
7 
8 /**
9 * Create a new ResourceCollection instance.
10 *
11 * @param Collection $collection
12 * @return void
13 */
14 public function __construct(Collection $collection)
15 {
16 $this->collection = $collection;
17 }
18}
19 
20$collection = collect([1, 2, 3]);
21 
22$resource = $collection->pipeInto(ResourceCollection::class);
23 
24$resource->collection->all();
25 
26// [1, 2, 3]

pipeThrough()

pipeThrough 方法會將該 Collection 傳入給定之包含閉包的陣列,並回傳這些閉包的執行結果:

1$collection = collect([1, 2, 3]);
2 
3$result = $collection->pipeThrough([
4 function ($collection) {
5 return $collection->merge([4, 5]);
6 },
7 function ($collection) {
8 return $collection->sum();
9 },
10]);
11 
12// 15
1$collection = collect([1, 2, 3]);
2 
3$result = $collection->pipeThrough([
4 function ($collection) {
5 return $collection->merge([4, 5]);
6 },
7 function ($collection) {
8 return $collection->sum();
9 },
10]);
11 
12// 15

pluck()

pluck 方法可取得給定索引鍵內的所有值:

1$collection = collect([
2 ['product_id' => 'prod-100', 'name' => 'Desk'],
3 ['product_id' => 'prod-200', 'name' => 'Chair'],
4]);
5 
6$plucked = $collection->pluck('name');
7 
8$plucked->all();
9 
10// ['Desk', 'Chair']
1$collection = collect([
2 ['product_id' => 'prod-100', 'name' => 'Desk'],
3 ['product_id' => 'prod-200', 'name' => 'Chair'],
4]);
5 
6$plucked = $collection->pluck('name');
7 
8$plucked->all();
9 
10// ['Desk', 'Chair']

也可以指定產生的 Collection 要如何設定索引鍵:

1$plucked = $collection->pluck('name', 'product_id');
2 
3$plucked->all();
4 
5// ['prod-100' => 'Desk', 'prod-200' => 'Chair']
1$plucked = $collection->pluck('name', 'product_id');
2 
3$plucked->all();
4 
5// ['prod-100' => 'Desk', 'prod-200' => 'Chair']

pluck 方法也支援使用「點 (.)」標記法來取得巢狀數值:

1$collection = collect([
2 [
3 'name' => 'Laracon',
4 'speakers' => [
5 'first_day' => ['Rosa', 'Judith'],
6 ],
7 ],
8 [
9 'name' => 'VueConf',
10 'speakers' => [
11 'first_day' => ['Abigail', 'Joey'],
12 ],
13 ],
14]);
15 
16$plucked = $collection->pluck('speakers.first_day');
17 
18$plucked->all();
19 
20// [['Rosa', 'Judith'], ['Abigail', 'Joey']]
1$collection = collect([
2 [
3 'name' => 'Laracon',
4 'speakers' => [
5 'first_day' => ['Rosa', 'Judith'],
6 ],
7 ],
8 [
9 'name' => 'VueConf',
10 'speakers' => [
11 'first_day' => ['Abigail', 'Joey'],
12 ],
13 ],
14]);
15 
16$plucked = $collection->pluck('speakers.first_day');
17 
18$plucked->all();
19 
20// [['Rosa', 'Judith'], ['Abigail', 'Joey']]

若存在重複的索引鍵,則最後一個相符合的元素會被插入 pluck 後的 Collection:

1$collection = collect([
2 ['brand' => 'Tesla', 'color' => 'red'],
3 ['brand' => 'Pagani', 'color' => 'white'],
4 ['brand' => 'Tesla', 'color' => 'black'],
5 ['brand' => 'Pagani', 'color' => 'orange'],
6]);
7 
8$plucked = $collection->pluck('color', 'brand');
9 
10$plucked->all();
11 
12// ['Tesla' => 'black', 'Pagani' => 'orange']
1$collection = collect([
2 ['brand' => 'Tesla', 'color' => 'red'],
3 ['brand' => 'Pagani', 'color' => 'white'],
4 ['brand' => 'Tesla', 'color' => 'black'],
5 ['brand' => 'Pagani', 'color' => 'orange'],
6]);
7 
8$plucked = $collection->pluck('color', 'brand');
9 
10$plucked->all();
11 
12// ['Tesla' => 'black', 'Pagani' => 'orange']

pop()

pop 方法會從該 Collection 中移除最後一個項目並將其回傳:

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

可以將整數傳入 pop 方法以從 Collection 的結尾移除並回傳多個項目:

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

prepend()

prepend 方法會將項目加至該 Collection 的開頭:

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

也可以傳入第二個引數來指定要被加到前面之項目的索引鍵:

1$collection = collect(['one' => 1, 'two' => 2]);
2 
3$collection->prepend(0, 'zero');
4 
5$collection->all();
6 
7// ['zero' => 0, 'one' => 1, 'two' => 2]
1$collection = collect(['one' => 1, 'two' => 2]);
2 
3$collection->prepend(0, 'zero');
4 
5$collection->all();
6 
7// ['zero' => 0, 'one' => 1, 'two' => 2]

pull()

pull 方法根據項目的索引鍵來在該 Collection 中移除項目並將其回傳:

1$collection = collect(['product_id' => 'prod-100', 'name' => 'Desk']);
2 
3$collection->pull('name');
4 
5// 'Desk'
6 
7$collection->all();
8 
9// ['product_id' => 'prod-100']
1$collection = collect(['product_id' => 'prod-100', 'name' => 'Desk']);
2 
3$collection->pull('name');
4 
5// 'Desk'
6 
7$collection->all();
8 
9// ['product_id' => 'prod-100']

push()

push 方法會將項目加至該 Collection 的結尾:

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

put()

put 方法將給定的索引鍵與值設定至該 Collection 內:

1$collection = collect(['product_id' => 1, 'name' => 'Desk']);
2 
3$collection->put('price', 100);
4 
5$collection->all();
6 
7// ['product_id' => 1, 'name' => 'Desk', 'price' => 100]
1$collection = collect(['product_id' => 1, 'name' => 'Desk']);
2 
3$collection->put('price', 100);
4 
5$collection->all();
6 
7// ['product_id' => 1, 'name' => 'Desk', 'price' => 100]

random()

random 方法會從該 Collection 內回傳一個隨機的項目:

1$collection = collect([1, 2, 3, 4, 5]);
2 
3$collection->random();
4 
5// 4 - (隨機取得)
1$collection = collect([1, 2, 3, 4, 5]);
2 
3$collection->random();
4 
5// 4 - (隨機取得)

也可以傳入一個整數給 random 來指定要隨機取得幾個項目。當有明顯傳入要取得記得項目的時候,將總是回傳一個包含項目的 Collection:

1$random = $collection->random(3);
2 
3$random->all();
4 
5// [2, 4, 5] - (retrieved randomly)
1$random = $collection->random(3);
2 
3$random->all();
4 
5// [2, 4, 5] - (retrieved randomly)

若該 Collection 實體內的項目比所要求的還要少,則 random 方法會擲回一個 InvalidArgumentException

random 函式也接受傳入一個閉包,該閉包會收到目前 Collection 的實體:

1$random = $collection->random(fn ($items) => min(10, count($items)));
2 
3$random->all();
4 
5// [1, 2, 3, 4, 5] - (隨機取得)
1$random = $collection->random(fn ($items) => min(10, count($items)));
2 
3$random->all();
4 
5// [1, 2, 3, 4, 5] - (隨機取得)

range()

range 方法回傳一個包含了介於指定範圍內整數的 Collection:

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

reduce()

reduce 方法會將該 Collection 歸約 (Reduce) 為單一值,將各個迭代的結果傳送至接下來的迭代中:

1$collection = collect([1, 2, 3]);
2 
3$total = $collection->reduce(function ($carry, $item) {
4 return $carry + $item;
5});
6 
7// 6
1$collection = collect([1, 2, 3]);
2 
3$total = $collection->reduce(function ($carry, $item) {
4 return $carry + $item;
5});
6 
7// 6

第一次迭代時,$carry 的值為 null。不過,也可以通過將第二個引數傳給 reduce 來指定初始值:

1$collection->reduce(function ($carry, $item) {
2 return $carry + $item;
3}, 4);
4 
5// 10
1$collection->reduce(function ($carry, $item) {
2 return $carry + $item;
3}, 4);
4 
5// 10

reduce 方法也會將關聯式 Collection 的索引鍵傳入給定的回呼中:

1$collection = collect([
2 'usd' => 1400,
3 'gbp' => 1200,
4 'eur' => 1000,
5]);
6 
7$ratio = [
8 'usd' => 1,
9 'gbp' => 1.37,
10 'eur' => 1.22,
11];
12 
13$collection->reduce(function ($carry, $value, $key) use ($ratio) {
14 return $carry + ($value * $ratio[$key]);
15});
16 
17// 4264
1$collection = collect([
2 'usd' => 1400,
3 'gbp' => 1200,
4 'eur' => 1000,
5]);
6 
7$ratio = [
8 'usd' => 1,
9 'gbp' => 1.37,
10 'eur' => 1.22,
11];
12 
13$collection->reduce(function ($carry, $value, $key) use ($ratio) {
14 return $carry + ($value * $ratio[$key]);
15});
16 
17// 4264

reduceSpread()

reduceSpread 方法會將該 Collection 歸約 (Reduce) 為一組包含值的陣列,並將每次迭代的結果傳遞給下一個迭代。這個方法與 reduce 方法類似,不過 reduceSpread 接受多個初始值:

1[$creditsRemaining, $batch] = Image::where('status', 'unprocessed')
2 ->get()
3 ->reduceSpread(function ($creditsRemaining, $batch, $image) {
4 if ($creditsRemaining >= $image->creditsRequired()) {
5 $batch->push($image);
6 
7 $creditsRemaining -= $image->creditsRequired();
8 }
9 
10 return [$creditsRemaining, $batch];
11 }, $creditsAvailable, collect());
1[$creditsRemaining, $batch] = Image::where('status', 'unprocessed')
2 ->get()
3 ->reduceSpread(function ($creditsRemaining, $batch, $image) {
4 if ($creditsRemaining >= $image->creditsRequired()) {
5 $batch->push($image);
6 
7 $creditsRemaining -= $image->creditsRequired();
8 }
9 
10 return [$creditsRemaining, $batch];
11 }, $creditsAvailable, collect());

reject()

reject 方法會使用給定的閉包來過濾該 Collection。若某項目應自產生的 Collection 內移除,則該閉包應回傳 true

1$collection = collect([1, 2, 3, 4]);
2 
3$filtered = $collection->reject(function ($value, $key) {
4 return $value > 2;
5});
6 
7$filtered->all();
8 
9// [1, 2]
1$collection = collect([1, 2, 3, 4]);
2 
3$filtered = $collection->reject(function ($value, $key) {
4 return $value > 2;
5});
6 
7$filtered->all();
8 
9// [1, 2]

有關與 reject 相反的方法。請參考 [filter](#method-filter) 方法。

replace()

replace 方法與 merge 方法類似。不過,除了複寫有字串索引鍵的相符項目外,replace 還會複寫該 Collection 中符合數字索引鍵的項目:

1$collection = collect(['Taylor', 'Abigail', 'James']);
2 
3$replaced = $collection->replace([1 => 'Victoria', 3 => 'Finn']);
4 
5$replaced->all();
6 
7// ['Taylor', 'Victoria', 'James', 'Finn']
1$collection = collect(['Taylor', 'Abigail', 'James']);
2 
3$replaced = $collection->replace([1 => 'Victoria', 3 => 'Finn']);
4 
5$replaced->all();
6 
7// ['Taylor', 'Victoria', 'James', 'Finn']

replaceRecursive()

該方法與 replace 類似,但這個方法會遞迴僅各個陣列,並將相同的取代過程套用至內部的數值:

1$collection = collect([
2 'Taylor',
3 'Abigail',
4 [
5 'James',
6 'Victoria',
7 'Finn'
8 ]
9]);
10 
11$replaced = $collection->replaceRecursive([
12 'Charlie',
13 2 => [1 => 'King']
14]);
15 
16$replaced->all();
17 
18// ['Charlie', 'Abigail', ['James', 'King', 'Finn']]
1$collection = collect([
2 'Taylor',
3 'Abigail',
4 [
5 'James',
6 'Victoria',
7 'Finn'
8 ]
9]);
10 
11$replaced = $collection->replaceRecursive([
12 'Charlie',
13 2 => [1 => 'King']
14]);
15 
16$replaced->all();
17 
18// ['Charlie', 'Abigail', ['James', 'King', 'Finn']]

reverse()

reverse 方法會將該 Collection 項目的順序顛倒過來,但保留原來的索引鍵:

1$collection = collect(['a', 'b', 'c', 'd', 'e']);
2 
3$reversed = $collection->reverse();
4 
5$reversed->all();
6 
7/*
8 [
9 4 => 'e',
10 3 => 'd',
11 2 => 'c',
12 1 => 'b',
13 0 => 'a',
14 ]
15*/
1$collection = collect(['a', 'b', 'c', 'd', 'e']);
2 
3$reversed = $collection->reverse();
4 
5$reversed->all();
6 
7/*
8 [
9 4 => 'e',
10 3 => 'd',
11 2 => 'c',
12 1 => 'b',
13 0 => 'a',
14 ]
15*/

search 方法在該 Collection 中搜尋給定的值,並在找到後回傳其索引鍵。若找不到該項目,則會回傳 false

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

這裡的搜尋是使用「鬆散 (Loose)」比對的,這表示,一個整數值與一個有相同值的字串會被視為相等。若要使用「嚴格 (Strict)」比對,可傳入 true 作為該方法的第二個引數:

1collect([2, 4, 6, 8])->search('4', $strict = true);
2 
3// false
1collect([2, 4, 6, 8])->search('4', $strict = true);
2 
3// false

或者,也可以提供你自己的閉包來搜尋符合給定布林測試的第一個項目:

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

shift()

shift 方法會從該 Collection 中移除第一個項目並將其回傳:

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

可以將整數傳入 shift 方法以從 Collection 的開頭移除並回傳多個項目:

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

shuffle()

shuffle 方法會隨機排序該 Collection 內的項目:

1$collection = collect([1, 2, 3, 4, 5]);
2 
3$shuffled = $collection->shuffle();
4 
5$shuffled->all();
6 
7// [3, 2, 5, 1, 4] - (隨機產生)
1$collection = collect([1, 2, 3, 4, 5]);
2 
3$shuffled = $collection->shuffle();
4 
5$shuffled->all();
6 
7// [3, 2, 5, 1, 4] - (隨機產生)

skip()

skip 方法會從該 Collection 的開頭移除給定數量的元素,作為一個新的陣列回傳:

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

skipUntil()

skipUtil 方法會一直跳過,直到給定的回呼回傳 true。接著,會回傳該 Collection 中剩下的項目作為一個新的 Collection 實體:

1$collection = collect([1, 2, 3, 4]);
2 
3$subset = $collection->skipUntil(function ($item) {
4 return $item >= 3;
5});
6 
7$subset->all();
8 
9// [3, 4]
1$collection = collect([1, 2, 3, 4]);
2 
3$subset = $collection->skipUntil(function ($item) {
4 return $item >= 3;
5});
6 
7$subset->all();
8 
9// [3, 4]

也可以傳入一個簡單的值給 skipUntil 方法,來跳過直到找到指定項目之前的所有項目:

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

若找不到給定的值,或是回呼從未回傳 true,則 skipUntil 方法會回傳一個空 Collection。

skipWhile()

skipWhile 方法會在給定的回呼回傳 true 的時候從該 Collection 中跳過項目,並回傳該 Collection 中剩餘的項目作為一個新的 Collection:

1$collection = collect([1, 2, 3, 4]);
2 
3$subset = $collection->skipWhile(function ($item) {
4 return $item <= 3;
5});
6 
7$subset->all();
8 
9// [4]
1$collection = collect([1, 2, 3, 4]);
2 
3$subset = $collection->skipWhile(function ($item) {
4 return $item <= 3;
5});
6 
7$subset->all();
8 
9// [4]
exclamation

若該回呼從未回傳 true,則 skipWhile 方法會回傳一個空 Collection。

slice()

slice 方法會回傳該 Collection 從給定索引開始的部分:

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

若想限制回傳部分的大小,可傳入需要的大小作為該方法的第二個引數:

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

回傳的部分預設會保留索引鍵。若不想保留原始的索引鍵,可以使用 values 方法來重新索引這些項目。

sliding()

sliding 方法會以代表「Sliding Window」的方式將該 Collection 中的項目拆分為數個片段並回傳一個新的 Collection:

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

這個方法特別適合與 eachSpread 方法一起使用:

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

也可以傳入第二個可選的「區間 (step)」值,用來判斷每個片段中第一個項目的距離:

1$collection = collect([1, 2, 3, 4, 5]);
2 
3$chunks = $collection->sliding(3, step: 2);
4 
5$chunks->toArray();
6 
7// [[1, 2, 3], [3, 4, 5]]
1$collection = collect([1, 2, 3, 4, 5]);
2 
3$chunks = $collection->sliding(3, step: 2);
4 
5$chunks->toArray();
6 
7// [[1, 2, 3], [3, 4, 5]]

sole()

sole 方法會回傳該 Collection 中第一個且唯一一個通過給定真值條件測試的元素:

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

也可以傳入一組索引鍵/值配對給 sole 方法,sole 方法會回傳該 Collection 中符合給定索引鍵/值配對的第一個且唯一一個項目:

1$collection = collect([
2 ['product' => 'Desk', 'price' => 200],
3 ['product' => 'Chair', 'price' => 100],
4]);
5 
6$collection->sole('product', 'Chair');
7 
8// ['product' => 'Chair', 'price' => 100]
1$collection = collect([
2 ['product' => 'Desk', 'price' => 200],
3 ['product' => 'Chair', 'price' => 100],
4]);
5 
6$collection->sole('product', 'Chair');
7 
8// ['product' => 'Chair', 'price' => 100]

或者,也可以在不給定引數的情況下呼叫 sole,以在該 Collection 中只有一個元素時取得其第一個元素:

1$collection = collect([
2 ['product' => 'Desk', 'price' => 200],
3]);
4 
5$collection->sole();
6 
7// ['product' => 'Desk', 'price' => 200]
1$collection = collect([
2 ['product' => 'Desk', 'price' => 200],
3]);
4 
5$collection->sole();
6 
7// ['product' => 'Desk', 'price' => 200]

若該 Collection 中沒有能被 sole 方法回傳的元素,則會擲回一個 \Illuminate\Collections\ItemNotFoundException 例外。若有多於一個能被回傳的元素,則會擲回 \Illuminate\Collections\MultipleItemsFoundException 例外。

some()

contains 方法的別名。

sort()

sort 方法可排列該 Collection。經過排列的 Collection 會保留原始的陣列索引鍵,因此,在下列範例中我們使用了 values 方法來將索引鍵重設成連續的數字索引:

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

若有進階的排序需求,可以傳入包含自訂演算法的回呼給 sort。請參考 PHP 說明文件中的 uasort,該函式為 Collection 的 sort 方法內部所使用。

lightbulb

若有需要排序包含巢狀陣列或物件的 Collection,請參考 sortBysortByDesc 方法。

sortBy()

sortBy 方法可依照給定的索引鍵來排列該 Collection。經過排列的 Collection 會保留原始的陣列索引鍵,因此,在下列範例中我們使用了 values 方法來將索引鍵重設成連續的數字索引:

1$collection = collect([
2 ['name' => 'Desk', 'price' => 200],
3 ['name' => 'Chair', 'price' => 100],
4 ['name' => 'Bookcase', 'price' => 150],
5]);
6 
7$sorted = $collection->sortBy('price');
8 
9$sorted->values()->all();
10 
11/*
12 [
13 ['name' => 'Chair', 'price' => 100],
14 ['name' => 'Bookcase', 'price' => 150],
15 ['name' => 'Desk', 'price' => 200],
16 ]
17*/
1$collection = collect([
2 ['name' => 'Desk', 'price' => 200],
3 ['name' => 'Chair', 'price' => 100],
4 ['name' => 'Bookcase', 'price' => 150],
5]);
6 
7$sorted = $collection->sortBy('price');
8 
9$sorted->values()->all();
10 
11/*
12 [
13 ['name' => 'Chair', 'price' => 100],
14 ['name' => 'Bookcase', 'price' => 150],
15 ['name' => 'Desk', 'price' => 200],
16 ]
17*/

sortBy 方法也接受排序旗標作為其第二引數:

1$collection = collect([
2 ['title' => 'Item 1'],
3 ['title' => 'Item 12'],
4 ['title' => 'Item 3'],
5]);
6 
7$sorted = $collection->sortBy('title', SORT_NATURAL);
8 
9$sorted->values()->all();
10 
11/*
12 [
13 ['title' => 'Item 1'],
14 ['title' => 'Item 3'],
15 ['title' => 'Item 12'],
16 ]
17*/
1$collection = collect([
2 ['title' => 'Item 1'],
3 ['title' => 'Item 12'],
4 ['title' => 'Item 3'],
5]);
6 
7$sorted = $collection->sortBy('title', SORT_NATURAL);
8 
9$sorted->values()->all();
10 
11/*
12 [
13 ['title' => 'Item 1'],
14 ['title' => 'Item 3'],
15 ['title' => 'Item 12'],
16 ]
17*/

此外,也可以傳入你自己的閉包來判斷該如何排序該 Collection 的值:

1$collection = collect([
2 ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
3 ['name' => 'Chair', 'colors' => ['Black']],
4 ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
5]);
6 
7$sorted = $collection->sortBy(function ($product, $key) {
8 return count($product['colors']);
9});
10 
11$sorted->values()->all();
12 
13/*
14 [
15 ['name' => 'Chair', 'colors' => ['Black']],
16 ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
17 ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
18 ]
19*/
1$collection = collect([
2 ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
3 ['name' => 'Chair', 'colors' => ['Black']],
4 ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
5]);
6 
7$sorted = $collection->sortBy(function ($product, $key) {
8 return count($product['colors']);
9});
10 
11$sorted->values()->all();
12 
13/*
14 [
15 ['name' => 'Chair', 'colors' => ['Black']],
16 ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
17 ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
18 ]
19*/

若想以多個屬性來排序 Collection,可以傳入包含排序操作的陣列給 sortBy 方法。各個排序操作應為一個陣列,該陣列由欲排序屬性以及排序順序所組成:

1$collection = collect([
2 ['name' => 'Taylor Otwell', 'age' => 34],
3 ['name' => 'Abigail Otwell', 'age' => 30],
4 ['name' => 'Taylor Otwell', 'age' => 36],
5 ['name' => 'Abigail Otwell', 'age' => 32],
6]);
7 
8$sorted = $collection->sortBy([
9 ['name', 'asc'],
10 ['age', 'desc'],
11]);
12 
13$sorted->values()->all();
14 
15/*
16 [
17 ['name' => 'Abigail Otwell', 'age' => 32],
18 ['name' => 'Abigail Otwell', 'age' => 30],
19 ['name' => 'Taylor Otwell', 'age' => 36],
20 ['name' => 'Taylor Otwell', 'age' => 34],
21 ]
22*/
1$collection = collect([
2 ['name' => 'Taylor Otwell', 'age' => 34],
3 ['name' => 'Abigail Otwell', 'age' => 30],
4 ['name' => 'Taylor Otwell', 'age' => 36],
5 ['name' => 'Abigail Otwell', 'age' => 32],
6]);
7 
8$sorted = $collection->sortBy([
9 ['name', 'asc'],
10 ['age', 'desc'],
11]);
12 
13$sorted->values()->all();
14 
15/*
16 [
17 ['name' => 'Abigail Otwell', 'age' => 32],
18 ['name' => 'Abigail Otwell', 'age' => 30],
19 ['name' => 'Taylor Otwell', 'age' => 36],
20 ['name' => 'Taylor Otwell', 'age' => 34],
21 ]
22*/

當以多個屬性排序 Collection 時,也可以提供閉包來定義各個排序操作:

1$collection = collect([
2 ['name' => 'Taylor Otwell', 'age' => 34],
3 ['name' => 'Abigail Otwell', 'age' => 30],
4 ['name' => 'Taylor Otwell', 'age' => 36],
5 ['name' => 'Abigail Otwell', 'age' => 32],
6]);
7 
8$sorted = $collection->sortBy([
9 fn ($a, $b) => $a['name'] <=> $b['name'],
10 fn ($a, $b) => $b['age'] <=> $a['age'],
11]);
12 
13$sorted->values()->all();
14 
15/*
16 [
17 ['name' => 'Abigail Otwell', 'age' => 32],
18 ['name' => 'Abigail Otwell', 'age' => 30],
19 ['name' => 'Taylor Otwell', 'age' => 36],
20 ['name' => 'Taylor Otwell', 'age' => 34],
21 ]
22*/
1$collection = collect([
2 ['name' => 'Taylor Otwell', 'age' => 34],
3 ['name' => 'Abigail Otwell', 'age' => 30],
4 ['name' => 'Taylor Otwell', 'age' => 36],
5 ['name' => 'Abigail Otwell', 'age' => 32],
6]);
7 
8$sorted = $collection->sortBy([
9 fn ($a, $b) => $a['name'] <=> $b['name'],
10 fn ($a, $b) => $b['age'] <=> $a['age'],
11]);
12 
13$sorted->values()->all();
14 
15/*
16 [
17 ['name' => 'Abigail Otwell', 'age' => 32],
18 ['name' => 'Abigail Otwell', 'age' => 30],
19 ['name' => 'Taylor Otwell', 'age' => 36],
20 ['name' => 'Taylor Otwell', 'age' => 34],
21 ]
22*/

sortByDesc()

該方法的簽章與 sortBy 方法相同,但會以相反的順序來排序該 Collection。

sortDesc()

該方法會以與 sort 方法相反的順序來排序該 Collection:

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

sort 不同,sortDesc 不接受傳入閉包。可以使用 sort 方法並使用相反的比較來代替。

sortKeys()

sortKeys 方法以底層關聯式陣列的索引鍵來排序該 Collection:

1$collection = collect([
2 'id' => 22345,
3 'first' => 'John',
4 'last' => 'Doe',
5]);
6 
7$sorted = $collection->sortKeys();
8 
9$sorted->all();
10 
11/*
12 [
13 'first' => 'John',
14 'id' => 22345,
15 'last' => 'Doe',
16 ]
17*/
1$collection = collect([
2 'id' => 22345,
3 'first' => 'John',
4 'last' => 'Doe',
5]);
6 
7$sorted = $collection->sortKeys();
8 
9$sorted->all();
10 
11/*
12 [
13 'first' => 'John',
14 'id' => 22345,
15 'last' => 'Doe',
16 ]
17*/

sortKeysDesc()

該方法的簽章與 sortKeys 方法相同,但會以相反的順序來排序該 Collection。

sortKeysUsing()

sortKeysUsing 方法使用給定的回呼來以底層關聯式陣列的索引鍵排序該 Collection:

1$collection = collect([
2 'ID' => 22345,
3 'first' => 'John',
4 'last' => 'Doe',
5]);
6 
7$sorted = $collection->sortKeysUsing('strnatcasecmp');
8 
9$sorted->all();
10 
11/*
12 [
13 'first' => 'John',
14 'ID' => 22345,
15 'last' => 'Doe',
16 ]
17*/
1$collection = collect([
2 'ID' => 22345,
3 'first' => 'John',
4 'last' => 'Doe',
5]);
6 
7$sorted = $collection->sortKeysUsing('strnatcasecmp');
8 
9$sorted->all();
10 
11/*
12 [
13 'first' => 'John',
14 'ID' => 22345,
15 'last' => 'Doe',
16 ]
17*/

該回呼必須為回傳一個小於、等於、或大於 0 之整數的比較函式。更多資訊請參考 PHP 說明文件中有關 uksort 的部分。uksortsortKeysUsing 方法內部所使用的 PHP 函式。

splice()

splice 方法會自指定的索引開始移除一部分的項目並將其回傳:

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

可以傳入第二個引數來限制產生 Collection 的大小:

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

此外,也可以傳入一個包含用來取代自 Collection 內移除項目的新項目作為第三個引數:

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

split()

split 方法會將 Collection 拆解成給定數量的群組:

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

splitIn()

splitIn 方法會將 Collection 拆解成給定數量的群組,並會在將剩餘項目填至最後一個群組前先填滿非結尾的群組:

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