README

Collection-PHP

这是一个优秀的工具，可以让您在使用PHP数组时获得更干净、更舒适的使用体验

安装

如果您使用Composer来管理依赖项，您可以在您的composer.json文件中包含以下内容

"require": {
    "faguima/collection": "1.0.0"
}

或者

composer require faguima/collection

然后，在运行composer update或php composer.phar update后，您可以使用Composer的自动加载来加载该类

require 'vendor/autoload.php';

一个简单的例子

require 'vendor/autoload.php';

use Collection\Collection;

$collection = Collection::make([1, 2, 3]);

echo $collection->sum(); // 6
echo $collection->first(); // 1
echo $collection->last(); // 3

$filter = $collection->filter(function ($item) {
    return $item > 1;
});
echo $filter->sum(); // 5;

方法列表

all()

all方法简单地返回由集合表示的基础数组

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

// [1, 2, 3]

avg()

avg方法返回集合中所有项的平均值

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

// 3

如果集合包含嵌套数组或对象，您应该传递一个键来用于确定计算平均值的值

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

chunk()

chunk方法将集合拆分为多个给定大小的更小的集合

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

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]

contains()

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 ($key, $value) {
    return $value > 5;
});
// false

count()

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

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

diff()

diff方法将集合与另一个集合或纯PHP数组进行比较

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

each()

each方法遍历集合中的项，并将每个项传递给给定的回调

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

从您的回调中返回false以跳出循环

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

every()

every方法创建一个新的集合，该集合由每个第n个元素组成

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

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

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

except()

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

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

filter()

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

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

first()

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

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

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

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

// 1

flatten()

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

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

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']

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'],
        ],
    ]
*/

has()

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

$collection = collect(['account_id' => 1, 'product' => 'Desk']);
$collection->has('email');
// 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()

intersect 方法移除在给定的数组或集合中不存在任何值的任何值。

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

如您所见，结果集合将保留原始集合的键。

isEmpty()

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

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

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()

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 ($key, $value) {
    return $value < 3;
});
// 2

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

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

map()

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

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

max()

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

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

merge()

merge 方法将给定的数组合并到集合中。任何与集合中字符串键匹配的字符串键都会覆盖集合中的值。

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

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

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

min()

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

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

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 方法。

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']

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。如果该整数大于 1，则返回项目集合。

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

reduce()

reduce 方法将集合减少到单个值，将每个迭代的结果传递给后续迭代。

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

第一次迭代的 $carry 的值是 null；然而，您可以通过传递第二个参数给 reduce 来指定其初始值。

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

reject()

reject 方法使用给定的回调函数过滤集合。回调函数应返回 true，对于它希望从结果集合中删除的任何项目。

$collection = collect([1, 2, 3, 4]);
$filtered = $collection->reject(function ($item) {
    return $item > 2;
});
$filtered->all();
// [1, 2]

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

reverse()

reverse 方法反转集合项目的顺序。

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

search()

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()

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

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

shuffle()

shuffle方法随机打乱集合中的项目

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

slice()

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]

返回的切片将具有新的、数字索引的键。如果您希望保留原始键，请将true作为方法的第三个参数传递。

sort()

sort方法对集合进行排序

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

排序后的集合保留原始数组键。在这个例子中，我们使用了values方法来将键重置为连续编号的索引。

有关对嵌套数组或对象集合进行排序的信息，请参阅sortBy和sortByDesc方法。

如果您需要对排序有更高级的需求，您可以传递一个回调函数来使用自己的算法进行排序。请参阅PHP文档中的usort，这是集合sort方法在底层调用的。

sortBy()

sortBy方法根据给定的键对集合进行排序

$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],
    ]
*/

排序后的集合保留原始数组键。在这个例子中，我们使用了values方法来将键重置为连续编号的索引。

您还可以传递自己的回调函数来确定如何对集合值进行排序

$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()

此方法与sortBy方法具有相同的签名，但将集合按相反的顺序排序。

splice()

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]

sum()

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()

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]

toArray()

toArray方法将集合转换为普通的PHP数组。

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

toJson()

toJson方法将集合转换为JSON格式。

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

transform()

transform方法遍历集合，并使用回调函数对集合中的每个项目进行调用。集合中的项目将被回调函数返回的值替换。

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

unique()

unique方法返回集合中的所有唯一项目

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

返回的集合保留原始数组键。在这个例子中，我们使用了values方法来将键重置为连续编号的索引。

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

$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'],
    ]
*/

values()

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],
    ]
*/

where()

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方法在检查项目值时使用严格比较。使用whereLoose方法进行“宽松”比较。

whereLoose()

此方法与where方法具有相同的签名；然而，所有值都使用“宽松”比较进行比较。

zip()

zip方法将给定数组的值与集合在相应索引处的值合并在一起

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