README

Hector 集合是Hector ORM的模块。可以独立于ORM使用。

安装

Composer

您可以使用Composer安装Hector 集合，这是推荐的安装方式。

$ composer require hectororm/collection

依赖

• PHP ^8.0

使用

集合可以像数组一样查看。但您不调用array_*()函数，而是直接调用集合的方法。

$collection = new Collection();
$collection = new Collection(['my', 'initial', 'array']);

$collection = new LazyCollection();
$collection = new LazyCollection(['my', 'initial', 'array']);

集合实现了CollectionInterface，只有Collection是可计数的。

可用的集合

• Collection: 默认集合
• LazyCollection: 懒集合，使用生成器来提高性能，但仅限唯一使用！

CollectionInterface方法

CollectionInterface::new(Closure|iterable $iterable): static

创建当前集合的新实例。

$collection = Collection::new(['foo', 'bar']);

Collection::count(): int

计算集合中的项目数量。

对于懒集合，遍历所有迭代器。

$collection = Collection::new(['foo', 'bar', 'baz']);
$collection->count(); // Returns `3`
count($collection); // Returns `3`

类似于count()函数。

CollectionInterface::getArrayCopy(): array

使用此方法获取集合的数组表示形式。

$collection = new Collection();
$collection->getArrayCopy(); // Returns `[]`

$collection = new Collection(['my', 'initial', new Collection(['array'])]);
$collection->getArrayCopy(); // Returns `['my', 'initial', ['array']]`

CollectionInterface::all(): array

使用此方法获取集合的所有值作为数组。

$collection = new Collection();
$collection->all(); // Returns `[]`

$collection = new Collection(['my', 'initial', new Collection(['array'])]);
$collection->all(); // Returns `['my', 'initial', new Collection(['array'])]`

CollectionInterface::isEmpty(): bool

知道集合是否为空。

Collection::new(['foo', 'bar'])->isEmpty(); // Returns FALSE
Collection::new()->isEmpty(); // Returns TRUE

CollectionInterface::isList(): bool

知道集合是否是列表。

Collection::new(['foo', 'bar'])->isList(); // Returns TRUE
Collection::new(['foo', 'b' => 'bar'])->isList(); // Returns FALSE

CollectionInterface::collect(): self

将当前集合的所有数据收集到另一个集合中。

对于懒集合，将剩余的所有项目收集到经典集合中。

$collection = Collection::new(['foo', 'bar']);
$newCollection = $collection->collect();

CollectionInterface::sort(callable|int|null $callback = null): static

对集合中的项目进行排序。

$collection = Collection::new(['foo', 'bar']);
$collection = $collection->sort();
$collection->getArrayCopy(); // Returns `['bar', 'foo']`

类似于PHP数组排序函数。

CollectionInterface::multiSort(callable ...$callback): static

对集合中的项目进行多级排序。

$collection = Collection::new([
    'l' => ['name' => 'Lemon', 'nb' => 1],
    'o' => ['name' => 'Orange', 'nb' => 1],
    'b1' => ['name' => 'Banana', 'nb' => 5],
    'b2' => ['name' => 'Banana', 'nb' => 1],
    'a1' => ['name' => 'Apple', 'nb' => 10],
    'a2' => ['name' => 'Apple', 'nb' => 1],
]);
$collection = $collection->sort(
    fn($item1, $item2) => $item1['name'] <=> $item2['name'],
    fn($item1, $item2) => $item1['nb'] <=> $item2['nb'],
);
$collection->getArrayCopy();
// Returns:
// [
//     'a2' => ['name' => 'Apple', 'nb' => 1],
//     'a1' => ['name' => 'Apple', 'nb' => 10],
//     'b2' => ['name' => 'Banana', 'nb' => 1],
//     'b1' => ['name' => 'Banana', 'nb' => 5],
//     'l' => ['name' => 'Lemon', 'nb' => 1],
//     'o' => ['name' => 'Orange', 'nb' => 1],
// ]`

CollectionInterface::filter(?callable $callback = null): static

使用回调过滤项目。

$collection = Collection::new([1, 10, 20, 100]);
$collection = $collection->filter(fn($value) => $value >= 20);
$collection->getArrayCopy(); // Returns `[20, 100]`

类似于array_filter()函数。

CollectionInterface::filterInstanceOf(string|object ...$class): static

使用对象实例比较过滤项目。

$collection = Collection::new([new stdClass(), new SimpleXMLElement()]);
$collection = $collection->filterInstanceOf(stdClass::class);
$collection->getArrayCopy(); // Returns `[object<stdClass>]`

类似于is_a()函数。

CollectionInterface::map(callable $callback): static

在项目上应用回调并返回回调的结果。

类似于array_map()函数。

CollectionInterface::each(callable $callback): static

在项目上应用回调并返回项目。

类似于array_walk()函数。

CollectionInterface::search(callable|mixed $needle): int|string|false

使用回调或值搜索项目的键。

$collection = Collection::new(['foo', 'bar', '1', 1, 'quxx']);
$collection->search(1); // Returns 2
$collection->search(1, true); // Returns 3
$collection->search(fn($value) => str_starts_with($value, 'bar')); // Returns 1

类似于array_search()函数。

CollectionInterface::get(int $index = 0): mixed

获取索引处的项目。

负索引，从集合的末尾开始。

$collection = Collection::new(['foo', 'bar', 'baz']);
$collection = $collection->get(); // Return `'foo'`
$collection = $collection->get(1); // Return `'bar'`
$collection = $collection->get(-1); // Return `'baz'`

CollectionInterface::first(?callable $callback = null): mixed

搜索第一个项目。

如果提供了回调，搜索第一个符合该回调的项目。

$collection = Collection::new(['foo', 'bar', 'baz']);
$collection = $collection->first(); // Return `'foo'`
$collection = $collection->first(fn($value) => str_starts_with('ba', $value)); // Return `'bar'`

CollectionInterface::last()

搜索最后一个项目。

如果提供了回调，搜索第一个符合该回调的项目。

$collection = Collection::new(['foo', 'bar', 'baz']);
$collection = $collection->last(); // Return `'baz'`
$collection = $collection->last(fn($value) => str_starts_with('ba', $value)); // Return `'baz'`

CollectionInterface::slice(int $offset, int|null $length = null): static

提取集合的一部分。

$collection = Collection::new(['foo', 'bar', 'baz']);
$collection->slice(0, 2)->getArrayCopy(); // Returns `['foo', 'bar']`
$collection->slice(1)->getArrayCopy(); // Returns `['bar', 'baz']`
$collection->slice(-2, 2)->getArrayCopy(); // Returns `['bar', 'baz']`
$collection->slice(-1)->getArrayCopy(); // Returns `['baz']`

类似于array_slice()函数。

CollectionInterface::contains(mixed $value, bool $strict = false): bool

集合包含值吗？

$collection = Collection::new(['foo', 'bar', '2', 'baz']);
$collection->contains('foo'); // Returns `true`
$collection->contains('qux'); // Returns `false`
$collection->contains(2); // Returns `true`
$collection->contains(2, true); // Returns `false`

类似于in_array()函数。

CollectionInterface::chunk(int $length): static

将集合项目分块为固定长度的集合。

$collection = Collection::new(['foo', 'bar', 'baz']);
$collection = $collection->chunck(2); // Returns 2 collections
$collection->getArrayCopy(); // Returns `[['foo', 'bar'], ['baz']]`

类似于array_chunk()函数。

CollectionInterface::keys(): static

获取集合项的键。

$collection = Collection::new(['k1' => 'foo', 1 => 'bar', 'k2' => 'baz']);
$collection->keys()->getArrayCopy(); // Returns `['k1', 1, 'k2']`

类似于 array_keys() 函数。

CollectionInterface::values(): 静态

获取集合项的值。

$collection = Collection::new(['k1' => 'foo', 1 => 'bar', 'k2' => 'baz']);
$collection->keys()->getArrayCopy(); // Returns `['foo', 'bar', 'baz']`

类似于 array_values() 函数。

CollectionInterface::unique(): 静态

获取集合项的唯一项。

$collection = Collection::new(['k1' => 'foo', 1 => 'foo', 'bar', 'k2' => 'baz']);
$collection->unique()->getArrayCopy(); // Returns `['k1' => 'foo', 'bar', 'k2' => 'baz']`

类似于 array_unique() 函数。

CollectionInterface::flip(): 静态

翻转键和值。

$collection = Collection::new(['k1' => 'foo', 1 => 'foo', 'bar', 'k2' => 'baz']);
$collection->flip()->getArrayCopy(); // Returns `['foo' => 'k1', 'bar' => 0, 'baz' => 'k2']`

类似于 array_flip() 函数。

CollectionInterface::reverse(bool $preserve_keys = false): 静态

反转项的顺序。

$collection = Collection::new(['k1' => 'foo', 'foo', 'bar', 'k2' => 'baz']);
$collection->reverse()->getArrayCopy(); // Returns `['k2' => 'baz', 0 => 'bar', 1 => 'foo', 'k1' => 'foo']`
$collection->reverse(true)->getArrayCopy(); // Returns `['k2' => 'baz', 1 => 'bar', 0 => 'foo', 'k1' => 'foo']`

类似于 array_reverse() 函数。

CollectionInterface::column(string|int|Closure|null $column_key, string|int|Closure|null $index_key = null): 静态

获取列值或重新索引集合。

$collection = Collection::new([
    ['k1' => 'foo', 'value' => 'foo value'],
    ['k1' => 'bar', 'value' => 'bar value'],
    ['k1' => 'baz', 'value' => 'baz value'],
]);
$collection = $collection->column('k1')->getArrayCopy(); // Returns `['foo', 'bar', 'baz']`
$collection = $collection->column('value', 'k1')->getArrayCopy(); // Returns `['foo' => 'foo value', 'bar' => 'bar value', 'baz' => 'baz value']`

类似于 array_column() 函数。

CollectionInterface::rand(int $length = 1): 静态

获取集合的随机值。

$collection = Collection::new(['foo', 'bar', 'baz']);
$collection = $collection->rand(2)->getArrayCopy(); // Returns 2 values random

类似于 array_rand() 函数。

CollectionInterface::sum(): float|int

获取值的总和。

$collection = Collection::new([1, 2, 3, 4]);
$collection->sum(); // Returns `10`

类似于 array_sum() 函数。

CollectionInterface::avg(): float|int

获取值的平均值。

$collection = Collection::new([1, 2, 3, 4]);
$collection->avg(); // Returns `2.5`

CollectionInterface::median(): float|int

获取值的中位数。

$collection = Collection::new([1, 3, 5, 7]);
$collection->median(); // Returns `4`

CollectionInterface::variance(): float|int

获取值的总体方差。

$collection = Collection::new([1, 1, 2, 2, 3, 5]);
$collection->variance(); // Returns `1.888888888889`

CollectionInterface::deviation(): float|int

获取值的总体偏差。

$collection = Collection::new([1, 3, 5, 7]);
$collection->deviation(); // Returns `2.2360679775`

CollectionInterface::reduce(callable $callback, mixed $initial = null): mixed

使用回调和可选的初始值缩减集合。

$collection = Collection::new([1, 2, 3, 4]);
$collection->reduce(fn($carry, $item) => $carry + $item, 10); // Returns `20`
$collection->reduce(fn($carry, $item) => $carry + $item); // Returns `10`

类似于 array_reduce() 函数。

Collection 方法

Collection 类实现了 ArrayAccess 接口，以便像数组一样操作集合。

Collection::append(mixed ...$value): 静态

将值追加到集合中。

$collection = Collection::new(['foo', 'bar']);
$collection->append('baz', 'qux')->getArrayCopy(); // Returns `['foo', 'bar', 'baz', 'qux']`

类似于 array_push() 函数。

Collection::prepend()

将值预置到集合中。

$collection = Collection::new(['foo', 'bar']);
$collection->prepend('baz', 'qux')->getArrayCopy(); // Returns `['baz', 'qux', 'foo', 'bar']`

类似于 array_unshift() 函数。

Collection::lazy(): CollectionInterface

从当前集合创建新的延迟集合。

LazyCollection 方法

延迟集合使用生成器来提高性能。集合的使用是唯一的，但可以链接。