README

Collections是一个简单轻量级的PHP集合类，旨在帮助以面向对象的方式方便地处理数据数组。

安装Axiom Collections

Axiom Collections需要PHP 7.0或更高版本。它未针对HHVM或旧版（受支持的）PHP版本进行测试，但本包中（除PHPUnit外）没有任何东西会导致失败。请注意，在这些情况下，不支持是未保证的。

建议您使用Composer安装此包。

$ composer require axiom/collections

此包符合PSR-1、PSR-2和PSR-4规范。如果您发现任何合规性问题，请通过pull request发送补丁。

使用Collections

创建集合

您有几个选项可用于创建新的Collection实例。

一种是通过直接创建类的实例来创建

$collection = new \Axiom\Collections\Collection([1, 2, 3]);

或者使用make静态辅助方法

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

方法

在本文档的其余部分，我们将遍历Collection类提供的所有可用方法。所有这些方法都可以链式调用以流畅地操作底层数组数据。最后，在几乎所有情况下，每个方法都将返回一个新的Collections实例，并在必要时保留集合的原始副本。

all()

all方法检索集合中的所有项目。

Collection::make([1, 2, 3])->all();

// [1, 2, 3]

count()

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

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

$collection->count();

// 4

each()

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

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

要从项目迭代中停止迭代并跳出循环，只需从您的回调函数中返回false即可。

$collection = $collection->each(function($item, $key) {
    if ($someCondition === true) {
        return false;
    }
});

exists()

exists方法确定给定的键是否存在于集合中。

$collection = Collection::make(['bot_id' => 1, 'name' => 'Loki']);

$collection->exists('name');

// true

filter()

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

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

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

$filtered->all();

// [3, 4]

有关filter的逆操作，请参阅reject方法。

first()

first方法返回集合中的第一个元素。

Collection::make([1, 2, 3, 4])->first();

// 1

flatten()

《flatten》方法返回一个新的集合实例，其中包含展开后的项目数组。

$collection = Collection::make([
    'name' => 'Kai',
    'profile' => [
        'age' => 28,
        'favorite_games' => ['Mass Effect', 'Oxygen Not Included', 'event[0]']
    ]
]);

$result = $collection->flatten();

$result->all();

// ['Kai', 28, 'Mass Effect', 'Oxygen Not Included', 'event[0]']

get()

《get》方法返回给定键的项目。

$collection = Collection::make(['foo' => 'bar', 'lorem' => 'ipsum']);

$result = $collection->get('lorem');

// ipsum

groupBy()

《groupBy》方法通过回调函数将项目分组为关联数组，并返回一个新的集合实例。

$collection = Collection::make([
    'foo' => ['type' => 'foobar'],
    'bar' => ['type' => 'foobar'],
    'lorem' => ['type' => 'lorem ipsum'],
    'ipsum' => ['type' => 'lorem ipsum']
]);

$result = $collection->groupBy(function($item) {
    return $item['type'];
});

$result->all();

//
[
    'foobar' => [
        'foo' => ['type' => 'foobar'],
        'bar' => ['type' => 'foobar'],
    ],
    'lorem ipsum' => [
        'lorem' => ['type' => 'lorem ipsum'],
        'ipsum' => ['type' => 'lorem ipsum']
    ]
]

keys()

《keys》方法返回一个新的集合实例，其中包含集合项的所有键。

$collection = Collection::make(['foo' => 'bar', 'lorem' => 'ipsum']);

$result = $collection->keys();

$result->all();

// ['foo', 'lorem']

last()

《last》方法返回集合中的最后一个元素。

Collection::make([1, 2, 3, 4])->last();

// 4

map()

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

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

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

$multiplied->all();

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

push()

《push》方法将项目追加到集合的末尾。

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

$collection->push(5);

$collection->all();

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

put()

《put》方法在集合中设置给定的键和值。

$collection = Collection::make(['bot_id' => 1, 'name' => 'Odin']);

$collection->put('name', 'Loki');

$collection->all();

// ['bot_id' => 1, 'name' => 'Loki']

reject()

《reject》方法使用给定的回调函数过滤集合。如果回调函数返回`true`，则项目应从结果集合中`移除`。

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

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

$filtered->all();

// [1, 2]

remove()

《remove》方法通过其键从集合中删除项目。

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

$collection->remove(0);

$collection->all();

// [1, 2, 3]

reverse()

《reverse》方法反转集合项目。

$collection = Collection::make([4, 1, 2, 3, 5])->reverse()->values()->all();

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

$collection = Collection::make([4, 1, 2, 3, 5])->sort()->reverse()->values()->all();

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

sort()

《sort》方法按升序对项目的值进行排序，或通过用户定义的比较函数进行排序。

$data = [4, 1, 2, 3, 5];

$collection = Collection::make($data)->sort()->values()->all();

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

$collection = Collection::make($data)->sort(function($a, $b) {
    if ($a === $b) {
        return 0;
    }

    return ($a < $b) ? -1 : 1;
})->values()->all();

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

sortByKey()

《sortByKey》方法按键的升序对项目进行排序，或通过用户定义的比较函数进行排序。

$data = [
    'foo4' => 1,
    'foo2' => 2,
    'foo5' => 3,
    'foo3' => 4,
    'foo1' => 5
];

$collection = Collection::make($data)->sortByKey()->values()->all();

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

$collection = Collection::make($data)->sortByKey(function($a, $b) {
    if ($a === $b) {
        return 0;
    }

    return ($a < $b) ? -1 : 1;
})->values()->all();

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

values()

《values》方法返回一个新的集合实例，其中包含集合项的所有值。

$collection = Collection::make(['foo' => 'bar', 'lorem' => 'ipsum']);

$result = $collection->values();

$result->all();

// ['bar', 'ipsum']