集合

简介
- 创建集合
- 扩展集合
可用方法
高阶信息
惰性集合

简介

Illuminate\Support\Collection 类提供了一个更具可读性和更便于处理数组数据的封装。具体请查看下方示例代码。我们使用 collect辅助函数从数组中创建一个新的集合实例，对其中每一个元素执行strtoupper 函数之后再删除所有的空元素：

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

正如你所见， Collection 类允许你链式调用其它方法，以达到在底层数组上流畅的执行 map 和 reduce 操作，通常，集合是不可变的，这意味着每一个Collection 方法都会返回一个新的 Collection 实例。

创建集合

如上所述，collect 辅助函数会为指定的数组返回一个新的Illuminate\Support\Collection实例。因此，我们可以非常容易的创建一个结合：

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

{tip} Eloquent 查询结果总是返回 Collection 实例。

扩展集合

集合都是「可宏扩展」(macroable) 的，它允许你在执行时将其它方法添加到 Collection 类。例如，通过下面的代码在Collection类中添加一个toUpper方法：

use Illuminate\Support\Collection;
use Illuminate\Support\Str;

Collection::macro('toUpper', function () {
    return $this->map(function ($value) {
        return Str::upper($value);
    });
});

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

$upper = $collection->toUpper();

// ['FIRST', 'SECOND']

通常，你应该在服务提供者内声明集合宏。

可用方法

接下来，我们将讨论每个 Collection 类可用的方法。记住，所有这些方法都可以链式调用以流畅地操作底层数组。此外，几乎所有方法都返回一个新的 Collection 实例，允许你在需要时保存集合的原始副本：

all
average
avg
chunk
collapse
collect
combine
concat
contains
containsStrict
count
countBy
crossJoin
dd
diff
diffAssoc
diffKeys
dump
duplicates
duplicatesStrict
each
eachSpread
every
except
filter
first
firstWhere
flatMap
flatten
flip
forget
forPage
get
groupBy
has
implode
intersect
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
pop
prepend
pull
push
put
random
reduce
reject
replace
replaceRecursive
reverse
search
shift
shuffle
skip
slice
some
sort
sortBy
sortByDesc
sortDesc
sortKeys
sortKeysDesc
splice
split
sum
take
tap
times
toArray
toJson
transform
union
unique
uniqueStrict
unless
unlessEmpty
unlessNotEmpty
unwrap
values
when
whenEmpty
whenNotEmpty
where
whereStrict
whereBetween
whereIn
whereInStrict
whereInstanceOf
whereNotBetween
whereNotIn
whereNotInStrict
whereNotNull
whereNull
wrap
zip

方法列表

`all()` {#collection-method .first-collection-method}

all 方法返回代表集合的底层数组：

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

// [1, 2, 3]

`average()` {#collection-method}

avg 方法的别名。

`avg()` {#collection-method}

avg 方法返回指定键的平均值：

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

// 20

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

// 2

`chunk()` {#collection-method}

chunk 方法把集合分割成多个指定大小的较小集合：

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

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

$chunks->toArray();

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

当使用如 Bootstrap 那样的栅格系统时，该方法在视图中相当有用。想象一下你有个想在栅格显示的 Eloquent 模型：

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

`collapse()` {#collection-method}

collapse 方法把一个多数组集合平铺为单个扁平的集合：

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

$collapsed = $collection->collapse();

$collapsed->all();

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

`combine()` {#collection-method}

combine 方法将一个集合的值作为键，与另一个数组或集合的值进行结合：

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

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

$combined->all();

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

`collect()` {#collection-method}

collect 方法返回一个包含当前集合所含元素的新 Collection 实例：

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

$collectionB = $collectionA->collect();

$collectionB->all();

// [1, 2, 3]

collect 方法从根本上对将懒集合转换为标准 Collection 实例有用:

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

$collection = $lazyCollection->collect();

get_class($collection);

// 'Illuminate\Support\Collection'

$collection->all();

// [1, 2, 3]

{提示} 当你有个 Enumerable 实例并需要一个非懒集合实例时， collect 方法相当有用。由于 collect() 是 Enumerable 契约的一部分，你可以安全地使用它以获取一个 Collection 实例。

`concat()` {#collection-method}

concat 方法在集合的末端附加指定的 数组 或集合值：

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

$concatenated = $collection->concat(['Jane Doe'])->concat(['name' => 'Johnny Doe']);

$concatenated->all();

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

`contains()` {#collection-method}

contains 方法检查集合有否包含指定的元素：

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

$collection->contains('Desk');

// true

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

// false

你也可以传递一个键/值对给 contains 方法，它将检查集合有否存在指定的键/值对：

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

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

// false

最后，你也可以传递一个回调函数给 contains 方法去执行你的真值检验：

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

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

// false

contains 方法用“松散”比较检查元素值，意味着整数值的字符串会被视同等值的整数。用 containsStrict 方法使用“严格”比较过滤。

`containsStrict()` {#collection-method}

这个方法和 contains 方法类似；但是它却是使用了「严格」比较来比较所有的值。

{tip} 这个方法的行为当使用 Eloquent Collections会被重写。

`count()` {#collection-method}

count 方法返回这个集合内集合项的总数量：

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

$collection->count();

// 4

`countBy()` {#collection-method}

countBy 方法计算集合中每个值的出现次数。默认情况下，该方法计算每个元素的出现次数：

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

$counted = $collection->countBy();

$counted->all();

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

但是，你也可以向 countBy传递一个回调函数来计算自定义的值出现的次数:

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

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

$counted->all();

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

`crossJoin()` {#collection-method}

crossJoin 方法交叉连接指定数组或集合的值，返回所有可能排列的笛卡尔积:

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

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

$matrix->all();

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

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

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

$matrix->all();

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

`dd()` {#collection-method}

dd 方法用于打印集合元素并中断脚本执行：

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

$collection->dd();

/*
    Collection {
        #items: array:2 [
            0 => "John Doe"
            1 => "Jane Doe"
        ]
    }
*/

如果你不想中断执行脚本，请使用 dump 方法替代。

`diff()` {#collection-method}

diff 方法将集合与其它集合或者 PHP 数组进行值的比较。然后返回原集合中存在而指定集合中不存在的值：

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

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

$diff->all();

// [1, 3, 5]

{tip} 这个方法的行为当使用Eloquent Collections时会被重写。

`diffAssoc()` {#collection-method}

diffAssoc 方法与另外一个集合或基于 PHP 数组的键 / 值对（keys and values）进行比较。这个方法将会返回原集合不存在于指定集合的键 / 值对：

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

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

$diff->all();

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

`diffKeys()` {#collection-method}

diffKeys方法和另外一个集合或 PHP 数组的键（keys）进行比较，然后返回原集合中存在而指定集合中不存在键所对应的键 / 值对：

$collection = collect([
    'one' => 10,
    'two' => 20,
    'three' => 30,
    'four' => 40,
    'five' => 50,
]);

$diff = $collection->diffKeys([
    'two' => 2,
    'four' => 4,
    'six' => 6,
    'eight' => 8,
]);

$diff->all();

// ['one' => 10, 'three' => 30, 'five' => 50]

`dump()` {#collection-method}

dump 方法用于打印集合项：

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

$collection->dump();

/*
    Collection {
        #items: array:2 [
            0 => "John Doe"
            1 => "Jane Doe"
        ]
    }
*/

如果要在打印集合后终止执行脚本，请使用 dd 方法代替。

`duplicates()` {#collection-method}

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

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

$collection->duplicates();

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

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

$employees = collect([
    ['email' => 'abigail@example.com', 'position' => 'Developer'],
    ['email' => 'james@example.com', 'position' => 'Designer'],
    ['email' => 'victoria@example.com', 'position' => 'Developer'],
])

$employees->duplicates('position');

// [2 => 'Developer']

`duplicatesStrict()` {#collection-method}

此方法与 duplicates 方法具有相同的签名；但是，所有值都以「严格」的方式进行比较。

`each()` {#collection-method}

each 方法用于循环集合项并将其传递到回调函数中：

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

如果你想中断对集合项的循环，那么就在你的回调函数中返回 false ：

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

`eachSpread()` {#collection-method}

eachSpread 方法用于循环集合项，将每个嵌套集合项的值传递给回调函数：

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

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

你可以通过在回调函数里返回 false 来中断循环：

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

`every()` {#collection-method}

every 方法可用于验证集合中的每一个元素是否通过指定的条件测试：

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

// false

如果集合为空， every 将返回 true ：
$collection = collect([]);

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

// true

`except()` {#collection-method}

except 方法返回集合中除了指定键之外的所有集合项：

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

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

$filtered->all();

// ['product_id' => 1]

与 except 对应的是 only 方法。

{tip} 这个方法的行为当使用 Eloquent Collections时会被重写。

`filter()` {#collection-method}

filter 方法使用给定的回调函数过滤集合，只保留那些通过指定条件测试的集合项：

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

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

$filtered->all();

// [3, 4]

如果没有提供回调函数，集合中所有返回 false 的元素都会被移除：

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

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

// [1, 2, 3]

filter 对应的是 reject 方法。

`first()` {#collection-method}

first 方法返回集合中通过指定条件测试的第一个元素：

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

// 3

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

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

// 1

`firstWhere()`

firstWhere 方法返回集合中含有指定键 / 值对的第一个元素：

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

$collection->firstWhere('name', 'Linda');

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

你也可以使用运算符来调用 firstWhere 方法：

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

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

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

$collection->firstWhere('age');

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

`flatMap()`

flatMap 方法遍历集合并将其中的每个值传递到给定的回调函数。可以通过回调函数修改集合项并返回它们，从而形成一个被修改过的新集合。然后，集合转化的数组是同级的：

$collection = collect([
    ['name' => 'Sally'],
    ['school' => 'Arkansas'],
    ['age' => 28]
]);

$flattened = $collection->flatMap(function ($values) {
    return array_map('strtoupper', $values);
});

$flattened->all();

// ['name' => 'SALLY', 'school' => 'ARKANSAS', 'age' => '28'];

`flatten()`

flatten 方法将多维集合转为一维集合：

$collection = collect(['name' => 'taylor', 'languages' => ['php', 'javascript']]);

$flattened = $collection->flatten();

$flattened->all();

// ['taylor', 'php', 'javascript'];

你可以选择性地传入「深度」参数：

$collection = collect([
    'Apple' => [
        ['name' => 'iPhone 6S', 'brand' => 'Apple'],
    ],
    'Samsung' => [
        ['name' => 'Galaxy S7', 'brand' => 'Samsung']
    ],
]);

$products = $collection->flatten(1);

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

/*
    [
        ['name' => 'iPhone 6S', 'brand' => 'Apple'],
        ['name' => 'Galaxy S7', 'brand' => 'Samsung'],
    ]
*/

在这个例子里，调用 flatten 时不传入深度参数的话也会将嵌套数组转成一维的，然后返回 ['iPhone 6S', 'Apple', 'Galaxy S7', 'Samsung'] 。传入深度参数能让你限制设置返回数组的层数。

`flip()`

flip 方法将集合的键和对应的值进行互换：

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

$flipped = $collection->flip();

$flipped->all();

// ['taylor' => 'name', 'laravel' => 'framework']

`forget()`

forget 方法将通过指定的键来移除集合中对应的内容：

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

$collection->forget('name');

$collection->all();

// ['framework' => 'laravel']

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

`forPage()`

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

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

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

$chunk->all();

// [4, 5, 6]

`get()`

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

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

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

// taylor

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

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

$value = $collection->get('foo', 'default-value');

// default-value

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

$collection->get('email', function () {
    return 'default-value';
});

// default-value

`groupBy()`

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

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

$grouped = $collection->groupBy('account_id');

$grouped->toArray();

/*
    [
        'account-x10' => [
            ['account_id' => 'account-x10', 'product' => 'Chair'],
            ['account_id' => 'account-x10', 'product' => 'Bookcase'],
        ],
        'account-x11' => [
            ['account_id' => 'account-x11', 'product' => 'Desk'],
        ],
    ]
*/

你可以传递一个回调函数用来代替一个字符串的 键。这个回调函数应该返回你希望用来分组的键的值：

$grouped = $collection->groupBy(function ($item, $key) {
    return substr($item['account_id'], -3);
});

$grouped->toArray();

/*
    [
        'x10' => [
            ['account_id' => 'account-x10', 'product' => 'Chair'],
            ['account_id' => 'account-x10', 'product' => 'Bookcase'],
        ],
        'x11' => [
            ['account_id' => 'account-x11', 'product' => 'Desk'],
        ],
    ]
*/

可以传递一个数组用于多重分组标准。每一个数组元素将对应多维数组内的相应级别：

$data = new Collection([
    10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
    20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
    30 => ['user' => 3, 'skill' => 2, 'roles' => ['Role_1']],
    40 => ['user' => 4, 'skill' => 2, 'roles' => ['Role_2']],
]);

$result = $data->groupBy([
    'skill',
    function ($item) {
        return $item['roles'];
    },
], $preserveKeys = true);

/*
[
    1 => [
        'Role_1' => [
            10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
            20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
        ],
        'Role_2' => [
            20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
        ],
        'Role_3' => [
            10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
        ],
    ],
    2 => [
        'Role_1' => [
            30 => ['user' => 3, 'skill' => 2, 'roles' => ['Role_1']],
        ],
        'Role_2' => [
            40 => ['user' => 4, 'skill' => 2, 'roles' => ['Role_2']],
        ],
    ],
];
*/

`has()`

has 方法判断集合中是否存在指定键：

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

$collection->has('product');

// true

$collection->has(['product', 'amount']);

// true

$collection->has(['amount', 'price']);

// false

`implode()`

implode方法用于合并集合项。其参数取决于集合项的类型。如果集合包含数组或对象，你应该传递你希望合并的属性的键，以及你希望放在值之间用来「拼接」的字符串：

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

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

// Desk, Chair

如果集合中包含简单的字符串或数值，只需要传入「拼接」用的字符串作为该方法的唯一参数即可：

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

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

`intersect()` {#collection-method}

intersect 方法从原集合中移除在指定 array 或集合中不存在的值。生成的集合将会保留原集合的键：

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

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

$intersect->all();

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

提示：使用 Eloquent Collections 方法时，会修改此方法的行为。

`intersectByKeys()` {#collection-method}

intersectByKeys 方法从原集合中移除在指定 array 或集合中不存在的任何键：

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

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

$intersect->all();

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

`isEmpty()` {#collection-method}

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

collect([])->isEmpty();

// true

`isNotEmpty()` {#collection-method}

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

collect([])->isNotEmpty();

// false

`join()` {#collection-method}

join 方法会将集合中的值用字符串连接：

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

`keyBy()` {#collection-method}

keyBy 方法以指定的键作为集合的键。如果多个集合项具有相同的键，则只有最后一个集合项会显示在新集合中：

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

$keyed = $collection->keyBy('product_id');

$keyed->all();

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

你还可以在这个方法传递一个回调函数。该回调函数返回的值会作为该集合的键：

$keyed = $collection->keyBy(function ($item) {
    return strtoupper($item['product_id']);
});

$keyed->all();

/*
    [
        'PROD-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
        'PROD-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
    ]
*/

`keys()` {#collection-method}

keys 方法返回集合中所有的键：

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

$keys = $collection->keys();

$keys->all();

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

`last()` {#collection-method}

last 方法返回集合中通过指定条件测试的最后一个元素：

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

// 2

不传入参数的情况下， last 方法会获取集合中最后一个元素。如果集合为空，方法将返回 null ：

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

// 4

`macro()` {#collection-method}

静态 macro 方法允许你在运行时将方法添加至 Collection 类。关于更多信息，请参阅扩展集合的文档。

`make()` {#collection-method}

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

`map()` {#collection-method}

map 方法遍历集合并将每一个值传入给定的回调函数。该回调函数可以任意修改集合项并返回，从而生成被修改过集合项的新集合：

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

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

$multiplied->all();

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

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

`mapInto()` {#collection-method}

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

class Currency
{
    /**
     * Create a new currency instance.
     *
     * @param  string  $code
     * @return void
     */
    function __construct(string $code)
    {
        $this->code = $code;
    }
}

$collection = collect(['USD', 'EUR', 'GBP']);

$currencies = $collection->mapInto(Currency::class);

$currencies->all();

// [Currency('USD'), Currency('EUR'), Currency('GBP')]

`mapSpread()` {#collection-method}

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

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

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

$sequence = $chunks->mapSpread(function ($even, $odd) {
    return $even + $odd;
});

$sequence->all();

// [1, 5, 9, 13, 17]

`mapToGroups()` {#collection-method}

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

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

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

$grouped->toArray();

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

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

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

`mapWithKeys()` {#collection-method}

mapWithKeys 方法遍历集合并将每个值传入给定的回调函数。该回调函数将返回一个包含单个键 / 值对的关联数组：

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

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

$keyed->all();

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

`max()`

max 方法返回指定键的最大值：

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

// 20

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

// 5

`median()`

median 方法返回指定键的中间值：

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

// 15

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

// 1.5

`merge()`

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

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

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

$merged->all();

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

如果给定的集合项为数字，则这些值将会追加在集合的最后：

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

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

$merged->all();

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

`mergeRecursive()`

mergeRecursive方法以递归的形式合并给定的数组或集合到原集合中，如果给定集合项的字符串键与原集合的字符串键一致，则会将给定的集合项的值以递归的形式合并到原集合的相同键中。

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

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

$merged->all();

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

`min()`

min 方法返回指定键的最小值：

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

// 10

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

// 1

`mode()`

mode 方法返回指定键的众数) ：

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

// [10]

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

// [1]

`nth()`

nth 方法创建由每隔 n 个元素组成的一个新集合：

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

$collection->nth(4);

// ['a', 'e']

你也可以设置指定的偏移位置作为第二个参数：

$collection->nth(4, 1);

// ['b', 'f']

`only()`

only 方法返回集合中所有指定键的集合项：

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

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

$filtered->all();

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

与 only 对应的是 except 方法。

注意：此方法在使用 Eloquent Collections时会被更改。
<a name="method-pad"></a>

`pad()`

pad 方法将使用给定的值填充数组，直到数组达到指定的大小。该方法的行为与 array_pad PHP 函数功能类似。

要填充到左侧，你应该使用负值。如果给定大小的绝对值小于或等于数组的长度，则不会发生填充：

$collection = collect(['A', 'B', 'C']);

$filtered = $collection->pad(5, 0);

$filtered->all();

// ['A', 'B', 'C', 0, 0]

$filtered = $collection->pad(-5, 0);

$filtered->all();

// [0, 0, 'A', 'B', 'C']

`partition()`

partition 方法可以和 PHP 函数中的 list 结合使用，用来分开通过指定条件的元素以及那些不通过指定条件的元素：

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

list($underThree, $equalOrAboveThree) = $collection->partition(function ($i) {
    return $i < 3;
});

$underThree->all();

// [1, 2]

$equalOrAboveThree->all();

// [3, 4, 5, 6]

`pipe()`

pipe 方法传入一个回调函数并返回结果：

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

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

// 6

`pluck()`

pluck 方法可以获取集合中指定键对应的所有值：

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

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

$plucked->all();

// ['Desk', 'Chair']

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

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

$plucked->all();

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

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

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

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

$plucked->all();

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

`pop()`

pop 从原集合返回并移除最后一个集合项：

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

$collection->pop();

// 5

$collection->all();

// [1, 2, 3, 4]

`prepend()`

prepend方法将指定的值添加的集合的开头：

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

$collection->prepend(0);

$collection->all();

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

你也可以传递第二个参数来设置新增加集合项的键：

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

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

$collection->all();

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

`pull()`

pull 方法把指定键对应的值从集合中移除并返回：

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

$collection->pull('name');

// 'Desk'

$collection->all();

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

`push()`

push 方法把指定的值追加到集合项的末尾：

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

$collection->push(5);

$collection->all();

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

`put()`

put 方法在集合内设置给定的键值对：

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

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

$collection->all();

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

`random()`

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

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

$collection->random();

// 4 - (retrieved randomly)

你可以选择传入一个整数到 random 来指定要获取的随即项的数量。只要你显示传递你希望接收的数量时，则会返回项目的集合：

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

$random->all();

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

如果集合的项小于指定的数量，则该方法将抛出 InvalidArgumentException。

`reduce()` {#collection-method}

reduce 方法将每次迭代的结果传递给下一次迭代直到集合减少为单个值：

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

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

// 6

第一次迭代时 $carry 的数值为 null； however，你也可以通过传入第二个参数到 reduce 来指定它的初始值：

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

// 10

`reject()` {#collection-method}

reject 方法使用指定的回调函数过滤集合。如果回调函数返回 true 就会把对应的集合项从集合中移除：

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

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

$filtered->all();

// [1, 2]

与 reject 方法对应的是 filter 方法。

`replace()` {#collection-method}

replace 方法类似于 merge ；但是，不仅可以覆盖匹配到的相同字符串键的集合项，而且也可以覆盖数字键的集合项：

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

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

$replaced->all();

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

`replaceRecursive()` {#collection-method}

这个方法类似 replace ，但是会以递归的形式将数组替换到具有相同键的集合项中：

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

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

$replaced->all();

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

`reverse()` {#collection-method}

reverse 方法用来倒转集合项的顺序，并保留原始的键：

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

$reversed = $collection->reverse();

$reversed->all();

/*
    [
        4 => 'e',
        3 => 'd',
        2 => 'c',
        1 => 'b',
        0 => 'a',
    ]
*/

`search()` {#collection-method}

search 方法在集合中搜索给定的值并返回它的键。如果没有找到，则返回 false 。

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

$collection->search(4);

// 1

使用「宽松」的方式进行搜索，这意味着具有整数值的字符串会被认为等于相同值的整数。使用「严格」的方式进行搜索，就传入 true 作为该方法的第二个参数：

$collection->search('4', true);

// false

或者，你可以通过传递回调函数来搜索通过条件测试的第一个集合项：

$collection->search(function ($item, $key) {
    return $item > 5;
});

// 2

`shift()` {#collection-method}

shift 方法移除并返回集合的第一个集合项：

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

$collection->shift();

// 1

$collection->all();

// [2, 3, 4, 5]

`shuffle()` {#collection-method}

shuffle 方法随机打乱集合项：

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

$shuffled = $collection->shuffle();

$shuffled->all();

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

`skip()` {#collection-method}

skip 方法返回除了给定的集合项数目的新集合：

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

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

$collection->all();

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

`slice()` {#collection-method}

slice 方法返回集合中给定索引开始后面的部分：

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

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

$slice->all();

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

如果你想限制返回内容的大小，可以将你期望的大小作为第二个参数传递到该方法：

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

$slice->all();

// [5, 6]

默认情况下，返回的内容将会保留原始键。如果你不希望保留原始键，你可以使用 values 方法来重新建立索引。

`some()` {#collection-method}

contains 方法的别名。.

`sort()` {#collection-method}

sort 方法对集合进行排序。排序后的集合会保留原数组的键，所以在这个例子我们将使用 values 方法去把键重置为连续编号的索引：

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

$sorted = $collection->sort();

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

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

如果你有更高级的排序需求，可以通过自己的算法将回调函数传递到 sort 。请参阅 PHP 文档的 uasort，这是集合的 sort 方法在底层所调用的。

{tip} 如果你需要对嵌套数组或对象进行排序，请参照 sortBy 和 sortByDesc 方法。

`sortBy()` {#collection-method}

sortBy 方法将根据指定键对集合进行排序。排序后的集合会保留原始数组的键，所以在这个例子中我们使用 values 方法将键重置为连续编号的索引：

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

$sorted = $collection->sortBy('price');

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

/*
    [
        ['name' => 'Chair', 'price' => 100],
        ['name' => 'Bookcase', 'price' => 150],
        ['name' => 'Desk', 'price' => 200],
    ]
*/

你也可以传递你自己的回调函数用于决定如何对集合的值进行排序：

$collection = collect([
    ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
    ['name' => 'Chair', 'colors' => ['Black']],
    ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
]);

$sorted = $collection->sortBy(function ($product, $key) {
    return count($product['colors']);
});

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

/*
    [
        ['name' => 'Chair', 'colors' => ['Black']],
        ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
        ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
    ]
*/

`sortByDesc()` {#collection-method}

该方法与 sortBy 方法一样，但是会以相反的顺序来对集合进行排序：

`sortDesc()` {#collection-method}

该方法与 sort 方法一样，但是会以相反的顺序来对集合进行排序：

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

$sorted = $collection->sortDesc();

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

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

`sortKeys()` {#collection-method}

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

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

$sorted = $collection->sortKeys();

$sorted->all();

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

`sortKeysDesc()` {#collection-method}

该方法与 sortKeys 方法一样，但是会以相反的顺序来对集合进行排序。

`splice()` {#collection-method}

splice 方法移除并返回指定索引开始的集合项片段：

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

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

$chunk->all();

// [3, 4, 5]

$collection->all();

// [1, 2]

你可以传递第二个参数用以限制被删除内容的大小：

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

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

$chunk->all();

// [3]

$collection->all();

// [1, 2, 4, 5]

此外，你可以传入含有新参数项的第三个参数来代替集合中删除的集合项：

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

$chunk = $collection->splice(2, 1, [10, 11]);

$chunk->all();

// [3]

$collection->all();

// [1, 2, 10, 11, 4, 5]

`split()` {#collection-method}

split 方法将集合按照给定的值拆分：

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

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

$groups->toArray();

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

`sum()` {#collection-method}

sum 方法返回集合内所有项的和：

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

// 15

如果集合包含嵌套数组或对象，则应该传入一个键来指定要进行求和的值：

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

$collection->sum('pages');

// 1272

另外，你可以传入自己的回调函数来决定要用集合中的哪些值进行求和：

$collection = collect([
    ['name' => 'Chair', 'colors' => ['Black']],
    ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
    ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
]);

$collection->sum(function ($product) {
    return count($product['colors']);
});

// 6

`take()` {#collection-method}

take 方法返回给定数量项的新集合：

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

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

$chunk->all();

// [0, 1, 2]

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

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

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

$chunk->all();

// [4, 5]

`tap()` {#collection-method}

tap 方法将给定的回调函数传入该集合，允许你在一个特定点「tap」集合，并在不影响集合本身的情况下对集合项执行某些操作：

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

// 1

`times()` {#collection-method}

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

$collection = Collection::times(10, function ($number) {
    return $number * 9;
});

$collection->all();

// [9, 18, 27, 36, 45, 54, 63, 72, 81, 90]

使用这个方法可以与工厂结合使用创建出 Eloquent 模型：

$categories = Collection::times(3, function ($number) {
    return factory(Category::class)->create(['name' => "Category No. $number"]);
});

$categories->all();

/*
    [
        ['id' => 1, 'name' => 'Category No. 1'],
        ['id' => 2, 'name' => 'Category No. 2'],
        ['id' => 3, 'name' => 'Category No. 3'],
    ]
*/

`toArray()` {#collection-method}

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

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

$collection->toArray();

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

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

`toJson()` {#collection-method}

toJson 方法将集合转换成 JSON 字符串：

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

$collection->toJson();

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

`transform()` {#collection-method}

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

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

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

$collection->all();

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

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

`union()` {#collection-method}

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

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

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

$union->all();

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

`unique()` {#collection-method}

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

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

$unique = $collection->unique();

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

// [1, 2, 3, 4]

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

$collection = collect([
    ['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'],
    ['name' => 'iPhone 5', 'brand' => 'Apple', 'type' => 'phone'],
    ['name' => 'Apple Watch', 'brand' => 'Apple', 'type' => 'watch'],
    ['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'],
    ['name' => 'Galaxy Gear', 'brand' => 'Samsung', 'type' => 'watch'],
]);

$unique = $collection->unique('brand');

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

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

你也可以通过传递自己的回调函数来确定对象的唯一性：

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

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

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

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

{tip} 这个方法的行为在使用 Eloquent Collections 时被修改。

`uniqueStrict()` {#collection-method}

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

`unless()` {#collection-method}

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

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

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

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

$collection->all();

// [1, 2, 3, 5]

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

`unlessEmpty()` {#collection-method}

whenNotEmpty 的别名方法。

`unlessNotEmpty()` {#collection-method}

whenEmpty 的别名方法。

`unwrap()` {#collection-method}

静态 unwrap 方法返回集合内部的可用值：

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

// ['John Doe']

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

// ['John Doe']

Collection::unwrap('John Doe');

// 'John Doe'

`values()` {#collection-method}

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

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

$values = $collection->values();

$values->all();

/*
    [
        0 => ['product' => 'Desk', 'price' => 200],
        1 => ['product' => 'Desk', 'price' => 200],
    ]
*/

`when()` {#collection-method}

当 when 方法的第一个参数传入为 true 时，将执行给定的回调函数：

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

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

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

$collection->all();

// [1, 2, 3, 4]

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

`whenEmpty()` {#collection-method}

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

$collection = collect(['michael', 'tom']);

$collection->whenEmpty(function ($collection) {
    return $collection->push('adam');
});

$collection->all();

// ['michael', 'tom']


$collection = collect();

$collection->whenEmpty(function ($collection) {
    return $collection->push('adam');
});

$collection->all();

// ['adam']


$collection = collect(['michael', 'tom']);

$collection->whenEmpty(function ($collection) {
    return $collection->push('adam');
}, function ($collection) {
    return $collection->push('taylor');
});

$collection->all();

// ['michael', 'tom', 'taylor']

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

`whenNotEmpty()` {#collection-method}

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

$collection = collect(['michael', 'tom']);

$collection->whenNotEmpty(function ($collection) {
    return $collection->push('adam');
});

$collection->all();

// ['michael', 'tom', 'adam']


$collection = collect();

$collection->whenNotEmpty(function ($collection) {
    return $collection->push('adam');
});

$collection->all();

// []


$collection = collect();

$collection->whenNotEmpty(function ($collection) {
    return $collection->push('adam');
}, function ($collection) {
    return $collection->push('taylor');
});

$collection->all();

// ['taylor']

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

`where()` {#collection-method}

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

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

$filtered = $collection->where('price', 100);

$filtered->all();

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

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

而且，你还可以将一个比较运算符作为第二个参数传递。

$collection = collect([
    ['name' => 'Jim', 'deleted_at' => '2019-01-01 00:00:00'],
    ['name' => 'Sally', 'deleted_at' => '2019-01-02 00:00:00'],
    ['name' => 'Sue', 'deleted_at' => null],
]);

$filtered = $collection->where('deleted_at', '!=', null);

$filtered->all();

/*
    [
        ['name' => 'Jim', 'deleted_at' => '2019-01-01 00:00:00'],
        ['name' => 'Sally', 'deleted_at' => '2019-01-02 00:00:00'],
    ]
*/

`whereStrict()` {#collection-method}

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

`whereBetween()` {#collection-method}

whereBetween 方法会筛选给定范围的集合：

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

$filtered = $collection->whereBetween('price', [100, 200]);

$filtered->all();

/*
    [
        ['product' => 'Desk', 'price' => 200],
        ['product' => 'Bookcase', 'price' => 150],
        ['product' => 'Door', 'price' => 100],
    ]
*/

`whereIn()` {#collection-method}

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

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

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

$filtered->all();

/*
    [
        ['product' => 'Desk', 'price' => 200],
        ['product' => 'Bookcase', 'price' => 150],
    ]
*/

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

`whereInStrict()` {#collection-method}

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

`whereInstanceOf()` {#collection-method}

whereInstanceOf 方法根据给定的类来过滤集合：

use App\User;
use App\Post;

$collection = collect([
    new User,
    new User,
    new Post,
]);

$filtered = $collection->whereInstanceOf(User::class);

$filtered->all();

// [App\User, App\User]

`whereNotBetween()` {#collection-method}

whereNotBetween 方法在指定的范围内过滤集合：

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

$filtered = $collection->whereNotBetween('price', [100, 200]);

$filtered->all();

/*
    [
        ['product' => 'Chair', 'price' => 80],
        ['product' => 'Pencil', 'price' => 30],
    ]
*/

`whereNotIn()` {#collection-method}

whereNotIn 方法根据未包含在指定数组的键 / 值对来对集合进行过滤：

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

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

$filtered->all();

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

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

`whereNotInStrict()` {#collection-method}

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

`whereNotNull()` {#collection-method}

whereNotNull 方法筛选给定键不为 NULL 的项：

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

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

$filtered->all();

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

`whereNull()` {#collection-method}

whereNull 方法筛选给定键为 NULL 的项：

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

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

$filtered->all();

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

`wrap()` {#collection-method}

静态 wrap 方法在适当的情况下将指定的值放在集合中：

$collection = Collection::wrap('John Doe');

$collection->all();

// ['John Doe']

$collection = Collection::wrap(['John Doe']);

$collection->all();

// ['John Doe']

$collection = Collection::wrap(collect('John Doe'));

$collection->all();

// ['John Doe']

`zip()` {#collection-method}

zip 方法将指定数组的值和相应索引的原集合的值合并在一起：

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

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

$zipped->all();

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

高阶消息传递

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

每个高阶消息传递都能作为集合实例的动态的属性来访问。例如，使用 each 高阶消息传递在集合中的每个对象上调用一个方法：

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

$users->each->markAsVip();

同样，我们可以使用 sum 高阶消息传递来收集 users 集合中的「投票」总数：

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

return $users->sum->votes;

懒集合

简介

{note} 注意：在进一步学习 Laravel 的懒集合之前，我们先花点时间熟悉一下 PHP generators.

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

例如，假设你的应用需要处理一个千兆字节的日志文件，同时利用 Laravel 的集合方法来解析这个日志文件。与其一次将整个文件读入内存，不如使用懒集合在给定时间仅将文件的一小部分保留在内存中：

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

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

    while (($line = fgets($handle)) !== false) {
        yield $line;
    }
})->chunk(4)->map(function ($lines) {
    return LogEntry::fromLines($lines);
})->each(function (LogEntry $logEntry) {
    // Process the log entry...
});

或者，假设你需要遍历 10000 个 Eloquent 模型。当使用传统的 Laravel 集合时，全部 10000 个 Eloquent 模型必须同时加载到内存中：

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

然而，查询构建器的 cursor 方法返回一个 LazyCollection 实例。这允许你对数据库只进行一次查询，而且一次只能在内存中加载一个 Eloquent 模型。在此例中， filter 回调只有在我们实际逐个迭代每个用户之后才会执行，这样可以大幅度减少内存使用：

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

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

懒集合

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

use Illuminate\Support\LazyCollection;

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

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

The Enumerable Contract

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

all
average
avg
chunk
collapse
collect
combine
concat
contains
containsStrict
count
countBy
crossJoin
dd
diff
diffAssoc
diffKeys
dump
duplicates
duplicatesStrict
each
eachSpread
every
except
filter
first
firstWhere
flatMap
flatten
flip
forPage
get
groupBy
has
implode
intersect
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
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

注意 LazyCollection类不提供使集合变动的方法（如 shift, pop, prepend 等）。

懒集合方法

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

`tapEach()` {#collection-method}

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

$lazyCollection = LazyCollection::times(INF)->tapEach(function ($value) {
    dump($value);
});

// Nothing has been dumped so far...

$array = $lazyCollection->take(3)->all();

// 1
// 2
// 3

`remember()` {#collection-method}

remember方法返回一个新的懒集合，这个集合已经记住了（缓存）已枚举所有的值，当再次枚举该集合时不会检索它们：

$users = User::cursor()->remember();

// 没执行任何查询

$users->take(5)->all();

// 执行了查询操作，并且前 5 个用户数据已经在数据库中查询完成

$users->take(20)->all();

// 前 5 个用户数据在缓存中获取，其余 15 个用户数据在数据库中查询

集合

集合

简介

创建集合

扩展集合

可用方法

方法列表

all() {#collection-method .first-collection-method}

average() {#collection-method}

avg() {#collection-method}

chunk() {#collection-method}

collapse() {#collection-method}

combine() {#collection-method}

collect() {#collection-method}

concat() {#collection-method}

contains() {#collection-method}

containsStrict() {#collection-method}

count() {#collection-method}

countBy() {#collection-method}

crossJoin() {#collection-method}

dd() {#collection-method}

diff() {#collection-method}

diffAssoc() {#collection-method}

diffKeys() {#collection-method}

dump() {#collection-method}

duplicates() {#collection-method}

duplicatesStrict() {#collection-method}

each() {#collection-method}

eachSpread() {#collection-method}

every() {#collection-method}

except() {#collection-method}

filter() {#collection-method}

first() {#collection-method}

firstWhere()

flatMap()

flatten()

flip()

forget()

forPage()

get()

groupBy()

has()

implode()

intersect() {#collection-method}

intersectByKeys() {#collection-method}

isEmpty() {#collection-method}

isNotEmpty() {#collection-method}

join() {#collection-method}

keyBy() {#collection-method}

keys() {#collection-method}

last() {#collection-method}

macro() {#collection-method}

make() {#collection-method}

map() {#collection-method}

mapInto() {#collection-method}

mapSpread() {#collection-method}

mapToGroups() {#collection-method}

mapWithKeys() {#collection-method}

max()

median()

merge()

mergeRecursive()

min()

mode()

nth()

only()

pad()

partition()

pipe()

pluck()

pop()

prepend()

pull()

push()

put()

random()

reduce() {#collection-method}

reject() {#collection-method}

replace() {#collection-method}

replaceRecursive() {#collection-method}