集合

• 简介
  • 创建集合
  • 扩展集合
• 可用方法
• 高阶消息
• 惰性集合
  • 简介
  • 创建惰性集合
  • 可枚举契约
  • 惰性集合方法

简介

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

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

如您所见，Collection 类允许您链式调用其方法，以流畅地映射和缩减底层数组。通常，集合是不可变的，这意味着每个 Collection 方法都会返回一个全新的 Collection 实例。

创建集合

如上所述，collect 辅助函数为给定的数组返回一个新的 Illuminate\Support\Collection 实例。因此，创建一个集合就像这样简单

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

扩展集合

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

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

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

宏参数

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

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

可用方法

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

方法列表

after()

after 方法返回给定项之后的项。如果未找到给定项或该项是最后一项，则返回 null

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

此方法使用“松散”比较搜索给定项，这意味着包含整数值的字符串将被视为等于具有相同值的整数。要使用“严格”比较，您可以向方法提供 strict 参数

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

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

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

all()

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

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

average()

avg 方法的别名。

avg()

avg 方法返回给定键的平均值

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

before()

before 方法与 after 方法相反。它返回给定项之前的项。如果未找到给定项或该项是第一项，则返回 null

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

chunk()

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

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

当在视图中使用网格系统（如 Bootstrap）时，此方法尤其有用。例如，假设您有一个要显示在网格中的 Eloquent 模型集合

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

chunkWhile()

chunkWhile 方法根据给定回调的计算结果将集合分成多个较小的集合。传递给闭包的 $chunk 变量可用于检查上一个元素

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

collapse()

collapse 方法将数组集合折叠成单个扁平集合

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

collect()

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

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

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

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

combine()

combine 方法将集合的值作为键，与另一个数组或集合的值组合起来

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

concat()

concat 方法将给定的 array 或集合的值追加到另一个集合的末尾

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

concat 方法为追加到原始集合的项目重新编号索引键。 要在关联集合中保留键，请参阅 merge 方法。

contains()

contains 方法确定集合是否包含给定项目。 您可以传递一个闭包给 contains 方法，以确定集合中是否存在与给定真值测试匹配的元素

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

或者，您可以传递一个字符串给 contains 方法，以确定集合是否包含给定的项目值

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

您也可以传递一个键/值对给 contains 方法，该方法将确定集合中是否存在给定的键/值对

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

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

对于 contains 的反向操作，请参阅 doesntContain 方法。

containsOneItem()

containsOneItem 方法确定集合是否包含单个项目

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

containsStrict()

此方法与 contains 方法具有相同的签名；但是，所有值都使用“严格”比较进行比较。

count()

count 方法返回集合中项目的总数

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

countBy()

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

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

您可以传递一个闭包给 countBy 方法，以按自定义值计算所有项目

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

crossJoin()

crossJoin 方法将集合的值与给定的数组或集合进行交叉连接，返回具有所有可能排列的笛卡尔积

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

dd()

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

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

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

diff()

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

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

diffAssoc()

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

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

diffAssocUsing()

与 diffAssoc 不同，diffAssocUsing 接受用户提供的回调函数用于索引比较

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

回调必须是一个比较函数，该函数返回一个小于、等于或大于零的整数。 有关详细信息，请参阅 PHP 文档中关于 array_diff_uassoc 的信息，这是 diffAssocUsing 方法内部使用的 PHP 函数。

diffKeys()

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

$collection = collect([
    'one' => 10,
    'two' => 20,
    'three' => 30,
    'four' => 40,
    'five' => 50,
]);
 
$diff = $collection->diffKeys([
    'two' => 2,
    'four' => 4,
    'six' => 6,
    'eight' => 8,
]);
 
$diff->all();
 
// ['one' => 10, 'three' => 30, 'five' => 50]

doesntContain()

doesntContain 方法确定集合是否不包含给定项目。 您可以传递一个闭包给 doesntContain 方法，以确定集合中是否存在与给定真值测试不匹配的元素

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

或者，您可以传递一个字符串给 doesntContain 方法，以确定集合是否不包含给定的项目值

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

您也可以传递一个键/值对给 doesntContain 方法，该方法将确定集合中是否存在给定的键/值对

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

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

dot()

dot 方法将多维集合展平为单级集合，该集合使用“点”表示法来指示深度

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

dump()

dump 方法转储集合的项目

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

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

duplicates()

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

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

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

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

duplicatesStrict()

此方法与 duplicates 方法具有相同的签名；但是，所有值都使用“严格”比较进行比较。

each()

each 方法迭代集合中的项目并将每个项目传递给闭包

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

如果您想停止迭代项目，您可以从闭包返回 false

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

eachSpread()

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

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

您可以通过从回调返回 false 来停止迭代项目

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

ensure()

ensure 方法可用于验证集合的所有元素是否属于给定的类型或类型列表。 否则，将抛出 UnexpectedValueException

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

也可以指定诸如 string、int、float、bool 和 array 等原始类型

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

every()

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

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

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

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

except()

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

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

对于 except 的反向操作，请参阅 only 方法。

filter()

filter 方法使用给定的回调过滤集合，仅保留通过给定真值测试的项目

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

如果没有提供回调，则将删除集合中所有等效于 false 的条目

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

对于 filter 的反向操作，请参阅 reject 方法。

first()

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

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

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

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

firstOrFail()

firstOrFail 方法与 first 方法相同；但是，如果未找到结果，则会抛出 Illuminate\Support\ItemNotFoundException 异常

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

您也可以不带参数调用 firstOrFail 方法来获取集合中的第一个元素。 如果集合为空，则会抛出 Illuminate\Support\ItemNotFoundException 异常

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

firstWhere()

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

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

您也可以使用比较运算符调用 firstWhere 方法

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

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

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

flatMap()

flatMap 方法迭代集合并将每个值传递给给定的闭包。 闭包可以自由地修改项目并返回它，从而形成一个修改后的项目的新集合。 然后，数组被展平一级

$collection = collect([
    ['name' => 'Sally'],
    ['school' => 'Arkansas'],
    ['age' => 28]
]);
 
$flattened = $collection->flatMap(function (array $values) {
    return array_map('strtoupper', $values);
});
 
$flattened->all();
 
// ['name' => 'SALLY', 'school' => 'ARKANSAS', 'age' => '28'];

flatten()

flatten 方法将多维集合展平为单维

$collection = collect([
    'name' => 'taylor',
    'languages' => [
        'php', 'javascript'
    ]
]);
 
$flattened = $collection->flatten();
 
$flattened->all();
 
// ['taylor', 'php', 'javascript'];

如有必要，您可以传递一个“深度”参数给 flatten 方法

$collection = collect([
    'Apple' => [
        [
            'name' => 'iPhone 6S',
            'brand' => 'Apple'
        ],
    ],
    'Samsung' => [
        [
            'name' => 'Galaxy S7',
            'brand' => 'Samsung'
        ],
    ],
]);
 
$products = $collection->flatten(1);
 
$products->values()->all();
 
/*
    [
        ['name' => 'iPhone 6S', 'brand' => 'Apple'],
        ['name' => 'Galaxy S7', 'brand' => 'Samsung'],
    ]
*/

在此示例中，在不提供深度的情况下调用 flatten 也会展平嵌套数组，导致 ['iPhone 6S', 'Apple', 'Galaxy S7', 'Samsung']。 提供深度允许您指定将展平的嵌套数组的层数。

flip()

flip 方法将集合的键与其对应的值交换

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

forget()

forget 方法通过键从集合中删除项目

$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
 
// Forget a single key...
$collection->forget('name');
 
// ['framework' => 'laravel']
 
// Forget multiple keys...
$collection->forget(['name', 'framework']);
 
// []

forPage()

forPage 方法返回一个新集合，其中包含给定页码上存在的项目。 该方法接受页码作为第一个参数，每页显示的项目数作为第二个参数

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

get()

get 方法返回给定键的项目。 如果键不存在，则返回 null

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

您可以选择传递一个默认值作为第二个参数

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

您甚至可以传递一个回调作为方法的默认值。 如果指定的键不存在，则将返回回调的结果

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

groupBy()

groupBy 方法按给定键对集合的项目进行分组

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

您可以传递一个回调，而不是传递一个字符串 key。 回调应返回您希望用于分组的值

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

可以将多个分组标准作为数组传递。 每个数组元素将应用于多维数组中的相应级别

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

has()

has 方法确定集合中是否存在给定的键

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

hasAny()

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

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

implode()

implode 方法连接集合中的项目。 它的参数取决于集合中项目的类型。 如果集合包含数组或对象，则应传递要连接的属性的键，以及您希望在值之间放置的“胶水”字符串

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

如果集合包含简单的字符串或数值，您应该将“胶水”作为方法的唯一参数传递。

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

如果您想格式化要连接的值，可以将闭包传递给 implode 方法。

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

intersect()

intersect 方法会从原始集合中删除给定 array 或集合中不存在的任何值。结果集合将保留原始集合的键。

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

intersectAssoc()

intersectAssoc 方法将原始集合与另一个集合或 array 进行比较，返回所有给定集合中都存在的键/值对。

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

intersectByKeys()

intersectByKeys 方法会从原始集合中删除给定 array 或集合中不存在的任何键及其对应的值。

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

isEmpty()

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

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

isNotEmpty()

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

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

join()

join 方法使用字符串连接集合的值。使用此方法的第二个参数，您还可以指定如何将最后一个元素附加到字符串。

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

keyBy()

keyBy 方法使用给定的键来键控集合。如果多个项具有相同的键，则只有最后一个项会出现在新集合中。

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

您还可以将回调函数传递给该方法。回调函数应返回用于键控集合的值。

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

keys()

keys 方法返回集合的所有键。

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

last()

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

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

您也可以在不带任何参数的情况下调用 last 方法，以获取集合中的最后一个元素。如果集合为空，则返回 null。

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

lazy()

lazy 方法从底层项数组返回一个新的 LazyCollection 实例。

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

当您需要对包含许多项的大型 Collection 执行转换时，这尤其有用。

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

通过将集合转换为 LazyCollection，我们可以避免分配大量额外内存。虽然原始集合仍然将其值保存在内存中，但后续的过滤器将不会。因此，在过滤集合的结果时，实际上不会分配额外的内存。

macro()

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

make()

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

map()

map 方法遍历集合并将每个值传递给给定的回调函数。回调函数可以自由地修改项并返回它，从而形成一个修改后的项的新集合。

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

mapInto()

mapInto() 方法遍历集合，通过将值传递给构造函数来创建给定类的新实例。

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

mapSpread()

mapSpread 方法遍历集合的项，将每个嵌套的项值传递给给定的闭包。闭包可以自由地修改项并返回它，从而形成一个修改后的项的新集合。

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

mapToGroups()

mapToGroups 方法按给定的闭包对集合的项进行分组。闭包应返回包含单个键/值对的关联数组，从而形成一个分组值的新集合。

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

mapWithKeys()

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

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

max()

max 方法返回给定键的最大值。

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

median()

median 方法返回给定键的中值。

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

merge()

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

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

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

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

mergeRecursive()

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

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

min()

min 方法返回给定键的最小值。

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

mode()

mode 方法返回给定键的众数。

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

multiply()

multiply 方法创建集合中所有项的指定数量的副本。

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

nth()

nth 方法创建一个新集合，其中包含每个第 n 个元素。

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

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

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

only()

only 方法返回集合中具有指定键的项。

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

对于 only 的反向操作，请参阅 except 方法。

pad()

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

要向左填充，您应指定负大小。如果给定大小的绝对值小于或等于数组的长度，则不会进行任何填充。

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

partition()

partition 方法可以与 PHP 数组解构结合使用，以分隔通过给定真值测试的元素和未通过给定真值测试的元素。

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

percentage()

percentage 方法可用于快速确定集合中通过给定真值测试的项的百分比。

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

默认情况下，百分比将四舍五入到两位小数。但是，您可以通过向该方法提供第二个参数来自定义此行为。

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

pipe()

pipe 方法将集合传递给给定的闭包并返回执行的闭包的结果。

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

pipeInto()

pipeInto 方法创建给定类的新实例，并将集合传递给构造函数。

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

pipeThrough()

pipeThrough 方法将集合传递给给定的闭包数组，并返回执行的闭包的结果。

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

pluck()

pluck 方法检索给定键的所有值。

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