laravelphp 中文文档

介绍

php Illuminate\Support\Collection 类为处理数据数组提供了一个流畅、方便的包装器。 例如，查看以下代码。 我们将使用 php collect 助手从数组中创建一个新的集合实例，对每个元素运行 php strtoupper 函数，然后删除所有空元素：

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

如你所见，php Collection 类允许你链接其方法以执行流畅的映射和减少底层数组。一般来说，集合是不可变的，这意味着每个 php Collection 方法都会返回一个全新的 php Collection 实例。

创建集合

如上所述，php collect 帮助器为给定数组返回一个新的 php Illuminate\Support\Collection 实例。因此，创建一个集合非常简单：

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

技巧：Eloquent 查询的结果总是作为 php Collection 实例返回。

扩展集合

集合是「可宏化的」，它允许你在运行时向 php Collection 类添加其他方法。 php Illuminate\Support\Collection 类的 php macro 方法接受一个闭包，该闭包将在调用宏时执行。宏闭包可以通过 php $this 访问集合的其他方法，就像它是集合类的真实方法一样。例如，以下代码在 php Collection 类中添加了 php toUpper 方法：

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

通常，你应该在服务提供者的 php boot 方法中声明集合宏。

宏参数
如有必要，可以定义接受其他参数的宏：

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

可用的方法

对于剩余的大部分集合文档，我们将讨论 php Collection 类中可用的每个方法。请记住，所有这些方法都可以链式调用，以便流畅地操作底层数组。此外，几乎每个方法都会返回一个新的 php Collection 实例，允许你在必要时保留集合的原始副本：

all
average
avg
chunk
chunkWhile
collapse
collect
combine
concat
contains
containsOneItem
containsStrict
count
countBy
crossJoin
dd
diff
diffAssoc
diffKeys
doesntContain
dump
duplicates
duplicatesStrict
each
eachSpread
every
except
filter
first
firstOrFail
firstWhere
flatMap
flatten
flip
forget
forPage
get
groupBy
has
hasAny
implode
intersect
intersectAssoc
intersectByKeys
isEmpty
isNotEmpty
join
keyBy
keys
last
lazy
macro
make
map
mapInto
mapSpread
mapToGroups
mapWithKeys
max
median
merge
mergeRecursive
min
mode
nth
only
pad
partition
pipe
pipeInto
pipeThrough
pluck
pop
prepend
pull
push
put
random
range
reduce
reduceSpread
reject
replace
replaceRecursive
reverse
search
shift
shuffle
skip
skipUntil
skipWhile
slice
sliding
sole
some
sort
sortBy
sortByDesc
sortDesc
sortKeys
sortKeysDesc
sortKeysUsing
splice
split
splitIn
sum
take
takeUntil
takeWhile
tap
times
toArray
toJson
transform
undot
union
unique
uniqueStrict
unless
unlessEmpty
unlessNotEmpty
unwrap
value
values
when
whenEmpty
whenNotEmpty
where
whereStrict
whereBetween
whereIn
whereInStrict
whereInstanceOf
whereNotBetween
whereNotIn
whereNotInStrict
whereNotNull
whereNull
wrap
zip

方法列表

php all()
php all 方法返回由集合表示的底层数组：

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

php average()
php avg 方法的别名。

php avg()
php avg 方法返回给定键的 平均值：

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

php chunk()
php chunk 方法将集合分成多个给定大小的较小集合：

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

当使用诸如 Bootstrap 之类的网格系统时，此方法在 views 中特别有用。例如，假设你有一组 Eloquent 模型要在网格中显示：

  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

php chunkWhile()
php chunkWhile 方法根据给定回调的评估将集合分成多个更小的集合。传递给闭包的 php $chunk 变量可用于检查前一个元素：

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

php collapse()
php collapse 方法将数组集合折叠成一个单一的平面集合：

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

php collect()
php collect 方法返回一个新的 php Collection 实例，其中包含当前集合中的项目：

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

php collect 方法主要用于将 惰性集合 转换为标准的 php Collection 实例：

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

技巧：当你有一个 php Enumerable 的实例并且需要一个非惰性集合实例时，php collect 方法特别有用。由于 php collect() 是 php Enumerable 合约的一部分，你可以安全地使用它来获取 php Collection 实例。

php combine()
php combine 方法将集合的值作为键与另一个数组或集合的值组合：

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

php concat()
php concat 方法将给定的 php array 或集合的值附加到另一个集合的末尾：

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

php concat 方法在数字上重新索引连接到原始集合上的项目的键。要维护关联集合中的键，请参阅 merge 方法。

php contains()
php contains 方法确定集合是否包含给定项目。你可以将闭包传递给 php contains 方法，以确定集合中是否存在与给定真值测试匹配的元素：

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

或者，你可以将字符串传递给 php contains 方法，以确定集合是否包含给定的项目值：

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

你还可以将键/值对传递给 php contains 方法，该方法将确定给定对是否存在于集合中：

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

php contains 方法在检查项目值时使用“松散”比较，这意味着具有整数值的字符串将被视为等于具有相同值的整数。使用 php containsStrict 方法使用“严格”比较进行过滤。

对于 php contains 的逆操作，请参见 doesntContain 方法。

php containsOneItem()
php containsOneItem 方法决定了集合是否包含一个项目。

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

php containsStrict()
此方法与 php contains 方法具有相同的签名；但是，所有值都使用「严格」比较进行比较。

技巧：使用 Eloquent Collections 时会修改此方法的行为。

php count()
php count 方法返回集合中的项目总数：

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

php countBy()
php countBy 方法计算集合中值的出现次数。默认情况下，该方法计算每个元素的出现次数，允许你计算集合中元素的某些“类型”：

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

你将闭包传递给 php countBy 方法以按自定义值计算所有项目：

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

php crossJoin()
php crossJoin 方法在给定的数组或集合中交叉连接集合的值，返回具有所有可能排列的笛卡尔积：

  1. $collection = collect([1, 2]);
  3. $matrix = $collection->crossJoin(['a', 'b']);
  5. $matrix->all();
  7. /*
  8.     [
  9.         [1, 'a'],
  10.         [1, 'b'],
  11.         [2, 'a'],
  12.         [2, 'b'],
  13.     ]
  14. */
  16. $collection = collect([1, 2]);
  18. $matrix = $collection->crossJoin(['a', 'b'], ['I', 'II']);
  20. $matrix->all();
  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. */

php dd()
php dd 方法转储集合的项目并结束脚本的执行：

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

如果你不想停止执行脚本，请改用 php dump 方法。

php diff()
php diff 方法根据集合的值将集合与另一个集合或普通 PHP php array 进行比较。此方法将返回给定集合中不存在的原始集合中的值：

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

技巧：此方法的行为在使用 Eloquent Collections 时被修改。

php diffAssoc()
php diffAssoc 方法根据其键和值将集合与另一个集合或普通 PHP php array 进行比较。此方法将返回给定集合中不存在的原始集合中的键/值对：

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

php diffKeys()
php diffKeys 方法将集合与另一个集合或基于其键的普通 PHP php array 进行比较。此方法将返回给定集合中不存在的原始集合中的键/值对：

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

php doesntContain()
php doesntContain 方法确定集合是否不包含给定项目。你可以将闭包传递给 php doesntContain 方法，以确定集合中是否不存在与给定真值测试匹配的元素：

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

或者，你可以将字符串传递给 php doesntContain 方法，以确定集合是否不包含给定的项目值：

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

你还可以将键/值对传递给 php doesntContain 方法，该方法将确定给定对是否不存在于集合中：

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

php doesntContain 方法在检查项目值时使用「松散」比较，这意味着具有整数值的字符串将被视为等于具有相同值的整数。

php dump()
php dump 方法转储集合的项目：

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

如果要在转储集合后停止执行脚本，请改用 php dd 方法。

php duplicates()
php duplicates 方法从集合中检索并返回重复值：

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

如果集合包含数组或对象，你可以传递要检查重复值的属性的键：

  1. $employees = collect([
  2.     ['email' => 'abigail@example.com', 'position' => 'Developer'],
  3.     ['email' => 'james@example.com', 'position' => 'Designer'],
  4.     ['email' => 'victoria@example.com', 'position' => 'Developer'],
  5. ]);
  7. $employees->duplicates('position');
  9. // [2 => 'Developer']

php duplicatesStrict()
此方法与 php duplicates 方法具有相同的签名；但是，所有值都使用「严格」比较进行比较。

php each()
php each 方法遍历集合中的项目并将每个项目传递给闭包：

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

如果你想停止遍历这些项目，你可以从你的闭包中返回 php false：

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

php eachSpread()
php eachSpread 方法迭代集合的项目，将每个嵌套项目值传递给给定的回调：

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

你可以通过从回调中返回 php false 来停止遍历项目：

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

php every()
php every 方法可用于验证集合的所有元素是否通过给定的真值测试：

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

如果集合为空，php every 方法将返回 true：

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

php except()
php except 方法返回集合中的所有项目，除了具有指定键的项目：

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

对于 php except 的反义词，请参见 only 方法。

技巧：此方法的行为在使用 Eloquent Collections 时被修改。

php filter()
php filter 方法使用给定的回调过滤集合，只保留那些通过给定真值测试的项目：

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

如果没有提供回调，则集合中所有相当于 php false 的条目都将被删除：

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

对于 php filter 的逆操作，请参见 reject 方法。

php first()
php first 方法返回集合中通过给定真值测试的第一个元素：

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

你也可以调用不带参数的 php first 方法来获取集合中的第一个元素。如果集合为空，则返回 php null：

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

php firstOrFail()
php firstOrFail 方法与 php first 方法相同；但是，如果没有找到结果，将抛出 php Illuminate/Support/ItemNotFoundException 异常。

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

你也可以调用 php firstOrFail 方法，没有参数，以获得集合中的第一个元素。如果集合是空的，将抛出一个 php Illuminate\Support\ItemNotFoundException 异常。

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

php firstWhere()
php firstWhere 方法返回集合中具有给定键/值对的第一个元素：

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

你还可以使用比较运算符调用 php firstWhere 方法：

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

与 where 方法一样，你可以将一个参数传递给 php firstWhere 方法。在这种情况下，php firstWhere 方法将返回给定项目键值为「真」的第一个项目：

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

php flatMap()
php flatMap 方法遍历集合并将每个值传递给给定的闭包。闭包可以自由修改项目并将其返回，从而形成一个新的修改项目集合。然后，数组被展平一层：

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

php flatten()
php flatten 方法将多维集合展平为一维：

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

如有必要，你可以向 php flatten 方法传递一个「深度」参数：

  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. ]);
  16. $products = $collection->flatten(1);
  18. $products->values()->all();
  20. /*
  21.     [
  22.         ['name' => 'iPhone 6S', 'brand' => 'Apple'],
  23.         ['name' => 'Galaxy S7', 'brand' => 'Samsung'],
  24.     ]
  25. */

在此示例中，调用 php flatten 而不提供深度也会使嵌套数组变平，从而导致 php ['iPhone 6S', 'Apple', 'Galaxy S7', 'Samsung']。提供深度允许你指定嵌套数组将被展平的级别数。

php flip()
php flip 方法将集合的键与其对应的值交换：

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

php forget()
该 php forget 方法将通过指定的键来移除集合中对应的元素：

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

注意：与大多数集合的方法不同的是， php forget 不会返回修改后的新集合；它会直接修改原集合。

php forPage()
该 php forPage 方法返回一个含有指定页码数集合项的新集合。这个方法接受页码数作为其第一个参数，每页显示的项数作为其第二个参数：

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

php get()
该 php get 方法返回指定键的集合项，如果该键在集合中不存在，则返回 null：

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

你可以任选一个默认值作为第二个参数传递：

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

你甚至可以将一个回调函数作为默认值传递。如果指定的键不存在，就会返回回调函数的结果：

  1. $collection->get('email', function () {
  2.     return 'taylor@example.com';
  3. });
  5. // taylor@example.com

php groupBy()
该 php groupBy 方法根据指定键对集合项进行分组：

  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. ]);
  7. $grouped = $collection->groupBy('account_id');
  9. $grouped->all();
  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. */

你可以传递回调，而不是传递字符串 php key。回调应返回你希望通过以下方式键入组的值：

  1. $grouped = $collection->groupBy(function (array $item, int $key) {
  2.     return substr($item['account_id'], -3);
  3. });
  5. $grouped->all();
  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. ]);
  8. $result = $data->groupBy(['skill', function (array $item) {
  9.     return $item['roles'];
  10. }], preserveKeys: true);
  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. */

php has()
php has 方法确定集合中是否存在给定键：

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

php hasAny()
php hasAny 方法确定在集合中是否存在任何给定的键。

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

php implode()
php implode 方法连接集合中的项目。它的参数取决于集合中项目的类型。如果集合包含数组或对象，你应该传递你希望加入的属性的键，以及你希望放置在值之间的「胶水」字符串：

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

如果集合包含简单的字符串或数值，则应将「胶水」作为唯一参数传递给该方法：

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

如果你想对被内部处理的值进行格式化，你可以给 php implode 方法传递一个闭包。

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

php intersect()
php intersect 方法从原始集合中删除任何不存在于给定 php array 或集合中的值。生成的集合将保留原始集合的键：

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

技巧：使用 Eloquent Collections 时会修改此方法的行为。

php intersectAssoc()
php intersectByKeys 方法从原始集合中删除给定 php array 或集合中不存在的任何键及其对应值：

  1. $collection = collect([
  2.     'color' => 'red',
  3.     'size' => 'M',
  4.     'material' => 'cotton'
  5. ]);
  7. $intersect = $collection->intersectAssoc([
  8.     'color' => 'blue',
  9.     'size' => 'M',
  10.     'material' => 'polyester'
  11. ]);
  13. $intersect->all();
  15. // ['size' => 'M']

php intersectByKeys()
php intersectByKeys 方法删除了原始集合中不存在于给定的数组或集合中的任何键和其相应的值。

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

php isEmpty()
如果集合为空，php isEmpty 方法返回 php true；否则，返回 php false：

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

php isNotEmpty()
如果集合不为空，php isNotEmpty 方法返回 php true；否则，返回 php false：

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

php join()
php join 方法将集合的值与字符串连接起来。使用此方法的第二个参数，你还可以指定最终元素应如何附加到字符串：

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

php keyBy()
php keyBy 方法通过给定键对集合进行键控。如果多个项目具有相同的键，则只有最后一个会出现在新集合中：

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

你也可以将回调传递给该方法。回调应通过以下方式返回值以作为集合的键：

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

php keys()
php keys 方法返回集合的所有键：

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

php last()
php last 方法返回集合中通过给定真值测试的最后一个元素：

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

你也可以调用不带参数的php last方法来获取集合中的最后一个元素。如果集合为空，则返回 php null：

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

php lazy()
php lazy 方法从底层的项目数组中返回一个新的 php LazyCollection 实例。

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

当你需要对一个包含许多项目的巨大 php Collection 进行转换时，这一点特别有用。

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

通过将集合转换为 php LazyCollection，我们避免了分配大量的额外内存。虽然原始集合仍然在内存中保留 它的 值，但后续的过滤器不会。因此，在过滤集合的结果时，几乎没有额外的内存被分配。

php macro()
静态php macro()方法允许你在运行时向「集合」类添加方法。有关详细信息，请参阅有关 扩展集合 的文档。

php make()
静态 php make 方法可以创建一个新的集合实例。请参照 创建集合 部分。

php map()
静态 php make 方法可以创建一个新的集合实例。请参照 创建集合 部分。

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

注意：与其他大多数集合方法一样， php map 会返回一个新的集合实例；它不会修改原集合。如果你想修改原集合，请使用 php transform 方法。

php mapInto()
该 php mapInto() 方法可以迭代集合，通过将值传递给构造函数来创建给定类的新实例：

  1. class Currency
  2. {
  3.     /**
  4.      * create a new currency instance.
  5.      */
  6.     function __construct(
  7.         public string $code
  8.     ) {}
  9. }
  11. $collection = collect(['USD', 'EUR', 'GBP']);
  13. $currencies = $collection->mapInto(Currency::class);
  15. $currencies->all();
  17. // [Currency('USD'), Currency('EUR'), Currency('GBP')]

php mapSpread()
该 php mapSpread 方法可以迭代集合，将每个嵌套项值给指定的回调函数。该回调函数可以自由修改该集合项并返回，从而生成被修改过集合项的新集合：

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

php mapToGroups()
该 php mapToGroups 方法通过给定的回调函数对集合项进行分组。该回调函数应该返回一个包含单个键 / 值对的关联数组，从而生成一个分组值的新集合：

  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. ]);
  16. $grouped = $collection->mapToGroups(function (array $item, int $key) {
  17.     return [$item['department'] => $item['name']];
  18. });
  20. $grouped->all();
  22. /*
  23.     [
  24.         'Sales' => ['John Doe', 'Jane Doe'],
  25.         'Marketing' => ['Johnny Doe'],
  26.     ]
  27. */
  29. $grouped->get('Sales')->all();
  31. // ['John Doe', 'Jane Doe']

php mapWithKeys()
php mapWithKeys 方法遍历集合并将每个值传递给给定的回调。回调应返回包含单个键/值对的关联数组：

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

php max()
php max 方法返回给定键的最大值：

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

php median()
php median 方法返回给定键的 中值：

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

php merge()
php merge 方法将给定的数组或集合与原始集合合并。如果给定项目中的字符串键与原始集合中的字符串键匹配，则给定项目的值将覆盖原始集合中的值：

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

如果给定项目的键是数字，则值将附加到集合的末尾：

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

php mergeRecursive()
php mergeRecursive 方法将给定的数组或集合递归地与原始集合合并。如果给定项目中的字符串键与原始集合中的字符串键匹配，则这些键的值将合并到一个数组中，这是递归完成的：

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

php min()
php min 方法返回给定键的最小值：

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

php mode()
php mode 方法返回给定键的 mode 值 “mode 值”)：

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

php nth()
php nth 方法创建一个由每个第 n 个元素组成的新集合：

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

你可以选择将起始偏移量作为第二个参数传递：

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

php only()
php only 方法返回集合中具有指定键的项目：

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

关于 php only 的反义词，见except 方法。

技巧：使用 Eloquent Collections 时会修改此方法的行为。

php pad()
php pad 方法将用给定的值填充数组，直到数组达到指定的大小。此方法的行为类似于 array_pad PHP 函数。

要向左填充，你应该指定一个负尺寸。如果给定大小的绝对值小于或等于数组的长度，则不会发生填充：

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

php partition()
该 php partition 方法可以与 PHP 数组解构相结合，以将通过给定真值测试的元素与未通过的元素分开：

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

php pipe()
该 php pipe 可以把集合放到回调参数中并返回回调的结果：

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

php pipeInto()
该 php pipeInto 方法创建一个给定类的新实例，并将集合传递给构造函数：

  1. class ResourceCollection
  2. {
  3.     /**
  4.      * create a new ResourceCollection instance.
  5.      */
  6.     public function __construct(
  7.       public Collection $collection,
  8.     ) {}
  9. }
  11. $collection = collect([1, 2, 3]);
  13. $resource = $collection->pipeInto(ResourceCollection::class);
  15. $resource->collection->all();
  17. // [1, 2, 3]

php pipeThrough()
该 php pipeThrough 方法将集合传递给给定的闭包数组并返回执行的闭包的结果：

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

php pluck()
该 php pluck 可以获取集合中指定键对应的所有值：

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

你也可以通过传入第二个参数来指定生成集合的 key（键）：

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

该 php 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. ]);
  16. $plucked = $collection->pluck('speakers.first_day');
  18. $plucked->all();
  20. // [['Rosa', 'Judith'], ['Abigail', 'Joey']]

如果存在重复键，则将最后一个匹配元素插入到 plucked 集合中：

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

php pop()
php pop 方法删除并返回集合中的最后一项：

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

你可以将整数传递给 php pop 方法以从集合末尾删除并返回多个项目：

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

php prepend()
php prepend 方法将一个项目添加到集合的开头：

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

你还可以传递第二个参数来指定前置项的键：

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

php pull()
php pull 方法通过它的键从集合中移除并返回一个项目：

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

php push()
php push 方法将一个项目附加到集合的末尾：

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

php put()
php put 方法在集合中设置给定的键和值：

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

php random()
php random 方法从集合中返回一个随机项：

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

你可以将一个整数传递给 php random，以指定要随机检索的项目数。当明确传递你希望接收的项目数时，始终返回项目集合：

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

如果集合实例的项目少于请求的项目，则 php random 方法将抛出 php InvalidArgumentException。

php random 方法也接受一个闭包，它将接收当前集合实例。

  1. use Illuminate\Support\Collection;
  3. $random = $collection->random(fn (Collection $items) => min(10, count($items)));
  5. $random->all();
  7. // [1, 2, 3, 4, 5] - (retrieved randomly)

php range()
php range 方法返回一个包含指定范围之间整数的集合：

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

php reduce()
php reduce 方法将集合减少为单个值，将每次迭代的结果传递给后续迭代：

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

php $carry 在第一次迭代时的值为 php null；但是，你可以通过将第二个参数传递给 php reduce 来指定其初始值：

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

php reduce 方法还将关联集合中的数组键传递给给定的回调：

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

php reduceSpread()
php reduceSpread 方法将集合缩减为一个值数组，将每次迭代的结果传递给后续迭代。此方法类似于 php reduce 方法；但是，它可以接受多个初始值：

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

php reject()
php reject 方法使用给定的闭包过滤集合。如果应从结果集合中删除项目，则闭包应返回 php true：

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

对于 php reject 方法的逆操作，请参见 php filter 方法。

php replace()

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

php replaceRecursive()
此方法的工作方式类似于 php replace，但它会重复出现在数组中并对内部值应用相同的替换过程：

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

php reverse()
php reverse 方法反转集合项的顺序，保留原始键：

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

php search()
php search 方法在集合中搜索给定值，如果找到则返回其键。如果未找到该项目，则返回 php false：

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

搜索是使用「松散」比较完成的，这意味着具有整数值的字符串将被视为等于具有相同值的整数。要使用「严格」比较，请将 php true 作为第二个参数传递给方法：

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

或者，你可以提供自己的闭包来搜索通过给定真值测试的第一个项目：

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

php shift()
php shift 方法从集合中移除并返回第一项：

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

你可以将整数传递给 php shift 方法以从集合的开头删除并返回多个项目：

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

php shuffle()
php shuffle 方法随机打乱集合中的项目：

  1. $collection = collect([1, 2, 3, 4, 5]);
  3. $shuffled = $collection->shuffle();
  5. $shuffled->all();
  7. // [3, 2, 5, 1, 4] - (generated randomly)

php skip()
php skip 方法返回一个新的集合，并从集合的开始删除指定数量的元素。

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

php skipUntil()
php skipUntil 方法跳过集合中的项目，直到给定的回调返回 php true，然后将集合中的剩余项目作为新的集合实例返回：

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

你还可以将一个简单的值传递给 php skipUntil 方法以跳过所有项目，直到找到给定值：

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

注意：如果没有找到给定的值或者回调从未返回 php true，php skipUntil 方法将返回一个空集合。

php skipWhile()
php skipWhile 方法在给定回调返回 php true 时跳过集合中的项目，然后将集合中的剩余项目作为新集合返回：

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

注意：如果回调从未返回 php false，php skipWhile 方法将返回一个空集合。

php slice()
php slice 方法返回从给定索引开始的集合的一个片断。

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

如果你想限制返回切片的大小，请将所需的大小作为第二个参数传给该方法。

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

返回的切片将默认保留键值。如果你不希望保留原始键，你可以使用 php values 方法来重新索引它们。

php sliding()
php sliding 方法返回一个新的块集合，表示集合中项目的「滑动窗口」视图：

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

这与 php eachSpread 方法结合使用特别有用：

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

你可以选择传递第二个「步长」值，该值确定每个块的第一项之间的距离：

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

php sole()
php sole 方法返回集合中第一个通过给定真值测试的元素，但只有在真值测试正好匹配一个元素的情况下。

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

你也可以向 php sole 方法传递一个键/值对，它将返回集合中第一个与给定对相匹配的元素，但只有当它正好有一个元素相匹配时。

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

另外，如果只有一个元素，你也可以调用没有参数的 php sole 方法来获得集合中的第一个元素。

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

如果集合中没有应该由 php sole 方法返回的元素，则会抛出 php \Illuminate\Collections\ItemNotFoundException 异常。如果应该返回多个元素，则会抛出 php \Illuminate\Collections\MultipleItemsFoundException。

php some()
php contains 方法的别名。

php sort()
php sort 方法对集合进行排序。排序后的集合保留了原始数组键，因此在下面的示例中，我们将使用 php values 方法将键重置为连续编号的索引：

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

如果你的排序需求更高级，你可以使用自己的算法将回调传递给「排序」。参考 PHP 文档 php uasort，就是集合的php sort方法 调用内部使用。

技巧：如果你需要对嵌套数组或对象的集合进行排序，请参阅 php sortBy 和 php sortByDesc 方法。

php sortBy()
php sortBy 方法按给定键对集合进行排序。排序后的集合保留了原始数组键，因此在下面的示例中，我们将使用 php values 方法将键重置为连续编号的索引：

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

php sortBy 方法接受 sort flags 作为其第二个参数：

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

或者，你可以传递自己的闭包来确定如何对集合的值进行排序：

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

如果你想按多个属性对集合进行排序，可以将排序操作数组传递给 php 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. ]);
  8. $sorted = $collection->sortBy([
  9.     ['name', 'asc'],
  10.     ['age', 'desc'],
  11. ]);
  13. $sorted->values()->all();
  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. ]);
  8. $sorted = $collection->sortBy([
  9.     fn (array $a, array $b) => $a['name'] <=> $b['name'],
  10.     fn (array $a, array $b) => $b['age'] <=> $a['age'],
  11. ]);
  13. $sorted->values()->all();
  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. */

php sortByDesc()
此方法与 php sortBy 方法具有相同的签名，但将以相反的顺序对集合进行排序。

php sortDesc()
此方法将按照与 php sort 方法相反的顺序对集合进行排序：

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

与 php sort 不同，你不能将闭包传递给 php sortDesc。相反，你应该使用 php sort 方法并反转比较。

php sortKeys()
php sortKeys 方法通过底层关联数组的键对集合进行排序：

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

php sortKeysDesc()
此方法与 php sortKeys 方法具有相同的签名，但将以相反的顺序对集合进行排序。

php sortKeysUsing()
php sortKeysUsing 方法使用回调通过底层关联数组的键对集合进行排序：

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

回调必须是返回小于、等于或大于零的整数的比较函数。有关更多信息，请参阅 php uksort 上的 PHP 文档，这是 PHP 函数 php sortKeysUsing 方法在内部使用。

php splice()
php splice 方法删除并返回从指定索引开始的项目切片：

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

你可以传递第二个参数来限制结果集合的大小：

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

此外，你可以传递包含新项目的第三个参数来替换从集合中删除的项目：

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

php split()
php split 方法将集合分成给定数量的组：

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

php splitIn()
php splitIn 方法将集合分成给定数量的组，在将剩余部分分配给最终组之前完全填充非终端组：

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

php sum()
php sum 方法返回集合中所有项目的总和：

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

如果集合包含嵌套数组或对象，则应传递一个键，用于确定要对哪些值求和：

  1. $collection = collect([
  2.     ['name' => 'JavaScript: The Good Parts', 'pages' => 176],
  3.     ['name' => 'JavaScript: The Definitive Guide', 'pages' => 1096],
  4. ]);
  6. $collection->sum('pages');
  8. // 1272

此外，你可以传递自己的闭包来确定要对集合的哪些值求和：

  1. $collection = collect([
  2.     ['name' => 'Chair', 'colors' => ['Black']],
  3.     ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
  4.     ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
  5. ]);
  7. $collection->sum(function (array $product) {
  8.     return count($product['colors']);
  9. });
  11. // 6

php take()
php take 方法返回一个具有指定数量项目的新集合：

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

你还可以传递一个负整数以从集合末尾获取指定数量的项目：

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

php takeUntil()
php takeUntil 方法返回集合中的项目，直到给定的回调返回 php true：

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

你还可以将一个简单的值传递给 php takeUntil 方法以获取项目，直到找到给定值：

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

注意：如果未找到给定值或回调从未返回 php true，则 php takeUntil 方法将返回集合中的所有项目。

php takeWhile()
php takeWhile 方法返回集合中的项目，直到给定的回调返回 php false：

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

注意：如果回调从不返回 php false，则 php takeWhile 方法将返回集合中的所有项目。

php tap()
php tap 方法将集合传递给给定的回调，允许你在特定点「点击」到集合中并在不影响集合本身的情况下对项目执行某些操作。然后集合由 php tap 方法返回：

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

php times()
静态 php times 方法通过调用给定次数的回调函数来创建新集合：

  1. $collection = Collection::times(10, function (int $number) {
  2.     return $number * 9;
  3. });
  5. $collection->all();
  7. // [9, 18, 27, 36, 45, 54, 63, 72, 81, 90]

php toArray()
该 php toArray 方法将集合转换成 PHP php array。如果集合的值是 Eloquent 模型，那也会被转换成数组：

  1. $collection = collect(['name' => 'Desk', 'price' => 200]);
  3. $collection->toArray();
  5. /*
  6.     [
  7.         ['name' => 'Desk', 'price' => 200],
  8.     ]
  9. */

注意：php toArray 也会将 php Arrayable 的实例、所有集合的嵌套对象转换为数组。如果你想获取原数组，可以使用 php all 方法。

php toJson()
该 php toJson 方法将集合转换成 JSON 字符串：

  1. $collection = collect(['name' => 'Desk', 'price' => 200]);
  3. $collection->toJson();
  5. // '{"name":"Desk", "price":200}'

php transform()
该 php transform 方法会遍历整个集合，并对集合中的每个元素都会调用其回调函数。集合中的元素将被替换为回调函数返回的值：

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

注意：与大多数集合方法不同，php transform 会修改集合本身。如果你想创建新集合，可以使用 php map 方法。

php undot()
php undot() 方法将使用「点」表示法的一维集合扩展为多维集合：

  1. $person = collect([
  2.     'name.first_name' => 'Marie',
  3.     'name.last_name' => 'Valentine',
  4.     'address.line_1' => '2992 Eagle Drive',
  5.     'address.line_2' => '',
  6.     'address.suburb' => 'Detroit',
  7.     'address.state' => 'MI',
  8.     'address.postcode' => '48219'
  9. ]);
  11. $person = $person->undot();
  13. $person->toArray();
  15. /*
  16.     [
  17.         "name" => [
  18.             "first_name" => "Marie",
  19.             "last_name" => "Valentine",
  20.         ],
  21.         "address" => [
  22.             "line_1" => "2992 Eagle Drive",
  23.             "line_2" => "",
  24.             "suburb" => "Detroit",
  25.             "state" => "MI",
  26.             "postcode" => "48219",
  27.         ],
  28.     ]
  29. */

php union()
该 php union 方法将给定数组添加到集合中。如果给定的数组含有与原集合一样的键，则首选原始集合的值：

  1. $collection = collect([1 => ['a'], 2 => ['b']]);
  3. $union = $collection->union([3 => ['c'], 1 => ['d']]);
  5. $union->all();
  7. // [1 => ['a'], 2 => ['b'], 3 => ['c']]

php unique()
该 php unique 方法返回集合中所有唯一项。返回的集合保留着原数组的键，所以在这个例子中，我们使用 php values 方法把键重置为连续编号的索引：

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

当处理嵌套数组或对象时，你可以指定用于确定唯一性的键：

  1. $collection = collect([
  2.     ['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'],
  3.     ['name' => 'iPhone 5', 'brand' => 'Apple', 'type' => 'phone'],
  4.     ['name' => 'Apple Watch', 'brand' => 'Apple', 'type' => 'watch'],
  5.     ['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'],
  6.     ['name' => 'Galaxy Gear', 'brand' => 'Samsung', 'type' => 'watch'],
  7. ]);
  9. $unique = $collection->unique('brand');
  11. $unique->values()->all();
  13. /*
  14.     [
  15.         ['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'],
  16.         ['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'],
  17.     ]
  18. */

最后，你还可以将自己的闭包传递给该 php unique 方法，以指定哪个值应确定项目的唯一性：

  1. $unique = $collection->unique(function (array $item) {
  2.     return $item['brand'].$item['type'];
  3. });
  5. $unique->values()->all();
  7. /*
  8.     [
  9.         ['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'],
  10.         ['name' => 'Apple Watch', 'brand' => 'Apple', 'type' => 'watch'],
  11.         ['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'],
  12.         ['name' => 'Galaxy Gear', 'brand' => 'Samsung', 'type' => 'watch'],
  13.     ]
  14. */

该 php unique 方法在检查项目值时使用「宽松」模式比较，意味着具有整数值的字符串将被视为等于相同值的整数。你可以使用 php uniqueStrict 方法做「严格」模式比较。

技巧：这个方法的行为在使用 Eloquent 集合 时被修改。

php uniqueStrict()
这个方法与 php unique 方法一样，然而，所有的值是用「严格」模式来比较的。

php unless()
该 php unless 方法当传入的第一个参数不为 php true 的时候，将执行给定的回调函数：

  1. $collection = collect([1, 2, 3]);
  3. $collection->unless(true, function (Collection $collection) {
  4.     return $collection->push(4);
  5. });
  7. $collection->unless(false, function (Collection $collection) {
  8.     return $collection->push(5);
  9. });
  11. $collection->all();
  13. // [1, 2, 3, 5]

可以将第二个回调传递给该 php unless 方法。 php unless 当给方法的第一个参数计算结果为时，将执行第二个回调 php true:

  1. $collection = collect([1, 2, 3]);
  3. $collection->unless(true, function (Collection $collection) {
  4.     return $collection->push(4);
  5. }, function (Collection $collection) {
  6.     return $collection->push(5);
  7. });
  9. $collection->all();
  11. // [1, 2, 3, 5]

与 php unless 相反的，请参见 php when 方法。

php unlessEmpty()
php whenNotEmpty 的别名方法。

php unlessNotEmpty()
php whenEmpty 的别名方法。

php unwrap()
静态 php unwrap 方法返回集合内部的可用元素：

  1. Collection::unwrap(collect('John Doe'));
  3. // ['John Doe']
  5. Collection::unwrap(['John Doe']);
  7. // ['John Doe']
  9. Collection::unwrap('John Doe');
  11. // 'John Doe'

php value()
php value 方法从集合的第一个元素中检索一个给定的值。

  1. $collection = collect([
  2.     ['product' => 'Desk', 'price' => 200],
  3.     ['product' => 'Speaker', 'price' => 400],
  4. ]);
  6. $value = $collection->value('price');
  8. // 200

php values()
该 php values 方法返回键被重置为连续编号的新集合：

  1. $collection = collect([
  2.     10 => ['product' => 'Desk', 'price' => 200],
  3.     11 => ['product' => 'Desk', 'price' => 200],
  4. ]);
  6. $values = $collection->values();
  8. $values->all();
  10. /*
  11.     [
  12.         0 => ['product' => 'Desk', 'price' => 200],
  13.         1 => ['product' => 'Desk', 'price' => 200],
  14.     ]
  15. */

php when()
当 php when 方法的第一个参数传入为 php true 时，将执行给定的回调函数。
集合实例和给到 php when 方法的第一个参数将被提供给闭包。

  1. $collection = collect([1, 2, 3]);
  3. $collection->when(true, function (Collection $collection, int $value) {
  4.     return $collection->push(4);
  5. });
  7. $collection->when(false, function (Collection $collection, int $value) {
  8.     return $collection->push(5);
  9. });
  11. $collection->all();
  13. // [1, 2, 3, 4]

可以将第二个回调传递给该 php when 方法。当给 php when 方法的第一个参数计算结果为 php false 时，将执行第二个回调：

  1. $collection = collect([1, 2, 3]);
  3. $collection->when(false, function (Collection $collection, int $value) {
  4.     return $collection->push(4);
  5. }, function (Collection $collection) {
  6.     return $collection->push(5);
  7. });
  9. $collection->all();
  11. // [1, 2, 3, 5]

与 php when 相反的方法，请查看 php unless 方法。

php whenEmpty()
该 php whenEmpty 方法是当集合为空时，将执行给定的回调函数：

  1. $collection = collect(['Michael', 'Tom']);
  3. $collection->whenEmpty(function (Collection $collection) {
  4.     return $collection->push('Adam');
  5. });
  7. $collection->all();
  9. // ['Michael', 'Tom']
  11. $collection = collect();
  13. $collection->whenEmpty(function (Collection $collection) {
  14.     return $collection->push('Adam');
  15. });
  17. $collection->all();
  19. // ['Adam']

当集合不为空时，可以将第二个闭包传递给 php whenEmpty 将要执行的方法：

  1. $collection = collect(['Michael', 'Tom']);
  3. $collection->whenEmpty(function (Collection $collection) {
  4.     return $collection->push('Adam');
  5. }, function (Collection $collection) {
  6.     return $collection->push('Taylor');
  7. });
  9. $collection->all();
  11. // ['Michael', 'Tom', 'Taylor']

与 php whenEmpty 相反的方法，请查看 php whenNotEmpty 方法。

php whenNotEmpty()
该 php whenNotEmpty 方法当集合不为空时，将执行给定的回调函数：

  1. $collection = collect(['michael', 'tom']);
  3. $collection->whenNotEmpty(function (Collection $collection) {
  4.     return $collection->push('adam');
  5. });
  7. $collection->all();
  9. // ['michael', 'tom', 'adam']
  11. $collection = collect();
  13. $collection->whenNotEmpty(function (Collection $collection) {
  14.     return $collection->push('adam');
  15. });
  17. $collection->all();
  19. // []

可以将第二个闭包传递给 php whenNotEmpty 将在集合为空时执行的方法：

  1. $collection = collect();
  3. $collection->whenNotEmpty(function (Collection $collection) {
  4.     return $collection->push('adam');
  5. }, function (Collection $collection) {
  6.     return $collection->push('taylor');
  7. });
  9. $collection->all();
  11. // ['taylor']

与 php whenNotEmpty 相反的方法，请查看 php whenEmpty 方法。

php where()
该 php where 方法通过给定的键 / 值对查询过滤集合的结果：

  1. $collection = collect([
  2.     ['product' => 'Desk', 'price' => 200],
  3.     ['product' => 'Chair', 'price' => 100],
  4.     ['product' => 'Bookcase', 'price' => 150],
  5.     ['product' => 'Door', 'price' => 100],
  6. ]);
  8. $filtered = $collection->where('price', 100);
  10. $filtered->all();
  12. /*
  13.     [
  14.         ['product' => 'Chair', 'price' => 100],
  15.         ['product' => 'Door', 'price' => 100],
  16.     ]
  17. */

该 php where 方法在检查集合项值时使用「宽松」模式比较，这意味着具有整数值的字符串会被认为等于相同值的整数。你可以使用 php whereStrict 方法进行「严格」模式比较。

而且，你还可以将一个比较运算符作为第二个参数传递。
支持的运算符是有 ‘===’, ‘！==’, ‘！=’, ‘==’, ‘=’, ‘<>’, ‘>’, ‘<’, ‘>=’, 和 ‘<=’。

  1. $collection = collect([
  2.     ['name' => 'Jim', 'deleted_at' => '2019-01-01 00:00:00'],
  3.     ['name' => 'Sally', 'deleted_at' => '2019-01-02 00:00:00'],
  4.     ['name' => 'Sue', 'deleted_at' => null],
  5. ]);
  7. $filtered = $collection->where('deleted_at', '!=', null);
  9. $filtered->all();
  11. /*
  12.     [
  13.         ['name' => 'Jim', 'deleted_at' => '2019-01-01 00:00:00'],
  14.         ['name' => 'Sally', 'deleted_at' => '2019-01-02 00:00:00'],
  15.     ]
  16. */

php whereStrict()
此方法和 php where 方法使用相似；但是它是「严格」模式去匹配值和类型。

php whereBetween()
该 php whereBetween 方法会筛选给定范围的集合：

  1. $collection = collect([
  2.     ['product' => 'Desk', 'price' => 200],
  3.     ['product' => 'Chair', 'price' => 80],
  4.     ['product' => 'Bookcase', 'price' => 150],
  5.     ['product' => 'Pencil', 'price' => 30],
  6.     ['product' => 'Door', 'price' => 100],
  7. ]);
  9. $filtered = $collection->whereBetween('price', [100, 200]);
  11. $filtered->all();
  13. /*
  14.     [
  15.         ['product' => 'Desk', 'price' => 200],
  16.         ['product' => 'Bookcase', 'price' => 150],
  17.         ['product' => 'Door', 'price' => 100],
  18.     ]
  19. */

php whereIn()
该 php whereIn 方法会根据包含给定数组的键 / 值对来过滤集合：

  1. $collection = collect([
  2.     ['product' => 'Desk', 'price' => 200],
  3.     ['product' => 'Chair', 'price' => 100],
  4.     ['product' => 'Bookcase', 'price' => 150],
  5.     ['product' => 'Door', 'price' => 100],
  6. ]);
  8. $filtered = $collection->whereIn('price', [150, 200]);
  10. $filtered->all();
  12. /*
  13.     [
  14.         ['product' => 'Desk', 'price' => 200],
  15.         ['product' => 'Bookcase', 'price' => 150],
  16.     ]
  17. */

php whereIn 方法在检查项目值时使用 “loose” 比较，这意味着具有整数值的字符串将被视为等于相同值的整数。使用 php whereInStrict 方法使用「strict」比较进行过滤。

php whereInStrict()
此方法与 php whereIn 方法具有相同的签名；但是，所有值都使用「strict」比较进行比较。

php whereInstanceOf()
php whereInstanceOf 方法按给定的类类型过滤集合：

  1. use App\Models\User;
  2. use App\Models\Post;
  4. $collection = collect([
  5.     new User,
  6.     new User,
  7.     new Post,
  8. ]);
  10. $filtered = $collection->whereInstanceOf(User::class);
  12. $filtered->all();
  14. // [App\Models\User, App\Models\User]

php whereNotBetween()
php whereNotBetween 方法通过确定指定项的值是否超出给定范围来过滤集合：

  1. $collection = collect([
  2.     ['product' => 'Desk', 'price' => 200],
  3.     ['product' => 'Chair', 'price' => 80],
  4.     ['product' => 'Bookcase', 'price' => 150],
  5.     ['product' => 'Pencil', 'price' => 30],
  6.     ['product' => 'Door', 'price' => 100],
  7. ]);
  9. $filtered = $collection->whereNotBetween('price', [100, 200]);
  11. $filtered->all();
  13. /*
  14.     [
  15.         ['product' => 'Chair', 'price' => 80],
  16.         ['product' => 'Pencil', 'price' => 30],
  17.     ]
  18. */

php whereNotIn()
php whereNotIn 方法从集合中删除具有给定数组中包含的指定项值的元素：

  1. $collection = collect([
  2.     ['product' => 'Desk', 'price' => 200],
  3.     ['product' => 'Chair', 'price' => 100],
  4.     ['product' => 'Bookcase', 'price' => 150],
  5.     ['product' => 'Door', 'price' => 100],
  6. ]);
  8. $filtered = $collection->whereNotIn('price', [150, 200]);
  10. $filtered->all();
  12. /*
  13.     [
  14.         ['product' => 'Chair', 'price' => 100],
  15.         ['product' => 'Door', 'price' => 100],
  16.     ]
  17. */

php whereNotIn 方法在检查项目值时使用「loose」比较，这意味着具有整数值的字符串将被视为等于具有相同值的整数。使用 php whereNotInStrict 方法使用「strict」比较进行过滤。

php whereNotInStrict()
这个方法与 php whereNotIn 方法类似；不同的是会使用「严格」模式比较。

php whereNotNull()
该 php whereNotNull 方法筛选给定键不为 php null的项：

  1. $collection = collect([
  2.     ['name' => 'Desk'],
  3.     ['name' => null],
  4.     ['name' => 'Bookcase'],
  5. ]);
  7. $filtered = $collection->whereNotNull('name');
  9. $filtered->all();
  11. /*
  12.     [
  13.         ['name' => 'Desk'],
  14.         ['name' => 'Bookcase'],
  15.     ]
  16. */

php whereNull()
该 php whereNull 方法筛选给定键为 php null的项：

  1. $collection = collect([
  2.     ['name' => 'Desk'],
  3.     ['name' => null],
  4.     ['name' => 'Bookcase'],
  5. ]);
  7. $filtered = $collection->whereNull('name');
  9. $filtered->all();
  11. /*
  12.     [
  13.         ['name' => null],
  14.     ]
  15. */

php wrap()
静态 php wrap 方法会将给定值封装到集合中：

  1. use Illuminate\Support\Collection;
  3. $collection = Collection::wrap('John Doe');
  5. $collection->all();
  7. // ['John Doe']
  9. $collection = Collection::wrap(['John Doe']);
  11. $collection->all();
  13. // ['John Doe']
  15. $collection = Collection::wrap(collect('John Doe'));
  17. $collection->all();
  19. // ['John Doe']

php zip()
该 php zip 方法在与集合的值对应的索引处合并给定数组的值：

  1. $collection = collect(['Chair', 'Desk']);
  3. $zipped = $collection->zip([100, 200]);
  5. $zipped->all();
  7. // [['Chair', 100], ['Desk', 200]]

Higher Order Messages

集合也提供对「高阶消息传递」的支持，即集合常见操作的快捷方式。支持高阶消息传递的集合方法有： php average、php avg、php contains、php each、php every、php filter、php first、php flatMap、php groupBy、php keyBy、php map、php max、php min、php partition、php reject、php skipUntil、php skipWhile、php some、php sortBy、php sortByDesc、php sum、php takeUntil、php takeWhile 和 php unique。

每个高阶消息都可以作为集合实例上的动态属性进行访问。例如，让我们使用 php each 高阶消息来调用集合中每个对象的方法：

  1. use App\Models\User;
  3. $users = User::where('votes', '>', 500)->get();
  5. $users->each->markAsVip();

同样，我们可以使用 php sum 高阶消息来收集用户集合的「votes」总数：

  1. $users = User::where('group', 'Development')->get();
  3. return $users->sum->votes;

惰性集合

介绍

注意：在进一步了解 Laravel 的惰性集合之前，花点时间熟悉一下 PHP 生成器.

为了补充已经强大的 php Collection 类，php LazyCollection 类利用 PHP 的 generators 允许你使用非常 大型数据集，同时保持较低的内存使用率。

例如，假设你的应用程序需要处理数 GB 的日志文件，同时利用 Laravel 的集合方法来解析日志。可以使用惰性集合在给定时间仅将文件的一小部分保留在内存中，而不是一次将整个文件读入内存：

  1. use App\Models\LogEntry;
  2. use Illuminate\Support\LazyCollection;
  4. LazyCollection::make(function () {
  5.     $handle = fopen('log.txt', 'r');
  7.     while (($line = fgets($handle)) !== false) {
  8.         yield $line;
  9.     }
  10. })->chunk(4)->map(function (array $lines) {
  11.     return LogEntry::fromLines($lines);
  12. })->each(function (LogEntry $logEntry) {
  13.     // Process the log entry...
  14. });

或者，假设你需要遍历 10,000 个 Eloquent 模型。使用传统 Laravel 集合时，所有 10,000 个 Eloquent 模型必须同时加载到内存中：

  1. use App\Models\User;
  3. $users = User::all()->filter(function (User $user) {
  4.     return $user->id > 500;
  5. });

但是，查询构建器的 php cursor 方法返回一个 php LazyCollection 实例。这允许你仍然只对数据库运行一个查询，而且一次只在内存中加载一个 Eloquent 模型。在这个例子中，php filter 回调在我们实际单独遍历每个用户之前不会执行，从而可以大幅减少内存使用量：

  1. use App\Models\User;
  3. $users = User::cursor()->filter(function (User $user) {
  4.     return $user->id > 500;
  5. });
  7. foreach ($users as $user) {
  8.     echo $user->id;
  9. }

创建惰性集合

要创建惰性集合实例，你应该将 PHP 生成器函数传递给集合的 php make 方法：

  1. use Illuminate\Support\LazyCollection;
  3. LazyCollection::make(function () {
  4.     $handle = fopen('log.txt', 'r');
  6.     while (($line = fgets($handle)) !== false) {
  7.         yield $line;
  8.     }
  9. });

枚举契约

php Collection 类上几乎所有可用的方法也可以在 php LazyCollection 类上使用。这两个类都实现了 php Illuminate\Support\Enumerable 契约，它定义了以下方法：

all
average
avg
chunk
chunkWhile
collapse
collect
combine
concat
contains
containsStrict
count
countBy
crossJoin
dd
diff
diffAssoc
diffKeys
dump
duplicates
duplicatesStrict
each
eachSpread
every
except
filter
first
firstOrFail
firstWhere
flatMap
flatten
flip
forPage
get
groupBy
has
implode
intersect
intersectAssoc
intersectByKeys
isEmpty
isNotEmpty
join
keyBy
keys
last
macro
make
map
mapInto
mapSpread
mapToGroups
mapWithKeys
max
median
merge
mergeRecursive
min
mode
nth
only
pad
partition
pipe
pluck
random
reduce
reject
replace
replaceRecursive
reverse
search
shuffle
skip
slice
sole
some
sort
sortBy
sortByDesc
sortKeys
sortKeysDesc
split
sum
take
tap
times
toArray
toJson
union
unique
uniqueStrict
unless
unlessEmpty
unlessNotEmpty
unwrap
values
when
whenEmpty
whenNotEmpty
where
whereStrict
whereBetween
whereIn
whereInStrict
whereInstanceOf
whereNotBetween
whereNotIn
whereNotInStrict
wrap
zip

注意：改变集合的方法（例如 php shift、php pop、php prepend 等）在 php LazyCollection 类中不可用。

惰性集合方法

除了在 php Enumerable 契约中定义的方法外， php LazyCollection 类还包含以下方法：

php takeUntilTimeout()
php takeUntilTimeout 方法返回新的惰性集合，它会在给定时间前去枚举集合值，之后集合将停止枚举：

  1. $lazyCollection = LazyCollection::times(INF)
  2.     ->takeUntilTimeout(now()->addMinute());
  4. $lazyCollection->each(function (int $number) {
  5.     dump($number);
  7.     sleep(1);
  8. });
  10. // 1
  11. // 2
  12. // ...
  13. // 58
  14. // 59

为了具体阐述此方法，请设想一个使用游标从数据库提交发票的例子。你可以定义一个 计划任务，它每十五分钟执行一次，并且只执行发票提交操作的最大时间是 14 分钟：

  1. use App\Models\Invoice;
  2. use Illuminate\Support\Carbon;
  4. Invoice::pending()->cursor()
  5.     ->takeUntilTimeout(
  6.         Carbon::createFromTimestamp(LARAVEL_START)->add(14, 'minutes')
  7.     )
  8.     ->each(fn (Invoice $invoice) => $invoice->submit());

php tapEach()
当 php each 方法为集合中每一个元素调用给定回调时， php tapEach 方法仅调用给定回调，因为这些元素正在逐个从列表中拉出：

  1. // 没有任何输出
  2. $lazyCollection = LazyCollection::times(INF)->tapEach(function (int $value) {
  3.     dump($value);
  4. });
  6. // 打印出三条数据
  7. $array = $lazyCollection->take(3)->all();
  9. // 1
  10. // 2
  11. // 3

php remember()
php remember 方法返回一个新的惰性集合，这个集合已经记住（缓存）已枚举的所有值，当再次枚举该集合时不会获取它们：

  1. // 没执行任何查询
  2. $users = User::cursor()->remember();
  4. //  执行了查询操作
  5. // The first 5 users are hydrated from the database...
  6. $users->take(5)->all();
  8. // 前 5 个用户数据从缓存中获取
  9. // The rest are hydrated from the database...
  10. $users->take(20)->all();

本文章首发在 网站上。