README

Hector Collection is the module of Hector ORM. Can be used independently of ORM.

Installation

Composer

You can install Hector Collection with Composer, it's the recommended installation.

$ composer require hectororm/collection

Dependencies

PHP ^8.0

Usage

Collection can be view like an array. But you don't call array_*() functions but directly methods of collection.

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

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

The collections implement CollectionInterface, only Collection is countable.

Available collections:

Collection: default collection
LazyCollection: lazy collection whose uses generators to improve performances, but is unique usage!

`CollectionInterface` methods

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

Create new instance of current collection.

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

`Collection::count(): int`

Count number of items in collection.

For lazy collection, all iterator is traversed.

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

Similar to count() function.

`CollectionInterface::getArrayCopy(): array`

Use method to get the array representation of your collection.

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

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

`CollectionInterface::all(): array`

Use method to get all values of your collection as 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`

Know if collection is empty.

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

`CollectionInterface::collect(): self`

Collect all data from current collection into another one.

For lazy collection, collect all remaining items into classic collection.

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

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

Sort items of collection.

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

Similar to PHP array sort functions.

`CollectionInterface::multiSort(callable ...$callback): self`

Multi sort items of collection.

$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): self`

Filter items with callback.

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

Similar to array_filter() function.

`CollectionInterface::filterInstanceOf(string|object ...$class): self`

Filter items with object instance comparison.

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

Similar to is_a() function.

`CollectionInterface::map(callable $callback): self`

Apply callback on items and return result of callback.

Similar to array_map() function.

`CollectionInterface::each(callable $callback): self`

Apply callback on items and return items.

Similar to array_walk() function.

`CollectionInterface::search(callable $callback): mixed`

Search item with callback.

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

Similar to array_search() function.

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

Get item at index.

Negative index, starts at end of collection.

$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`

Search first item.

If callback given, search first item whose respect callback.

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

Search last item.

If callback given, search first item whose respect callback.

$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): self`

Extract a slice of the collection.

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

Similar to array_slice() function.

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

Collection contains value?

$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`

Similar to in_array() function.

`CollectionInterface::chunk(int $length): self`

Chunk collection items into collection of fixed length.

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

Similar to array_chunk() function.

`CollectionInterface::keys(): self`

Get keys of collection items.

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

Similar to array_keys() function.

`CollectionInterface::values(): self`

Get values of collection items.

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

Similar to array_values() function.

`CollectionInterface::unique(): self`

Get uniques items of collection items.

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

Similar to array_unique() function.

`CollectionInterface::flip(): self`

Flip keys and values.

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

Similar to array_flip() function.

`CollectionInterface::column(string|int|Closure|null $column_key, string|int|Closure|null $index_key = null): self`

Get column value or reindex collection.

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

Similar to array_column() function.

`CollectionInterface::rand(int $length = 1): self`

Get random values of collection.

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

Similar to array_rand() function.

`CollectionInterface::sum(): float|int`

Get sum of values.

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

Similar to array_sum() function.

`CollectionInterface::avg(): float|int`

Get average of values.

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

`CollectionInterface::median(): float|int`

Get median of values.

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

`CollectionInterface::variance(): float|int`

Get population variance of values.

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

`CollectionInterface::deviation(): float|int`

Get population deviation of values.

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

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

Reduce collection with callback and optional initial value.

$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`

Similar to array_reduce() function.

`Collection` methods

Collection class implement ArrayAccess interface to allow to manipulate collection like an array.

`Collection::append(mixed ...$value): static`

Append value(s) to collection.

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

Similar to array_push() function.

`Collection::prepend()`

Prepend value(s) to collection.

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

Similar to array_unshift() function.

`Collection::lazy(): CollectionInterface`

New lazy collection from current collection.

`LazyCollection` methods

Lazy collection use generators to improve performances. Usage of a collection is unique, but can be chained.

hectororm / collection

Maintainers

Details

README

Installation

Composer

Dependencies

Usage

CollectionInterface methods

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

Collection::count(): int

CollectionInterface::getArrayCopy(): array

CollectionInterface::all(): array

CollectionInterface::isEmpty(): bool

CollectionInterface::collect(): self

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

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

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

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

CollectionInterface::map(callable $callback): self

CollectionInterface::each(callable $callback): self

CollectionInterface::search(callable $callback): mixed

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

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

CollectionInterface::last()

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

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

CollectionInterface::chunk(int $length): self

CollectionInterface::keys(): self

CollectionInterface::values(): self

CollectionInterface::unique(): self

CollectionInterface::flip(): self

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

CollectionInterface::rand(int $length = 1): self

CollectionInterface::sum(): float|int

CollectionInterface::avg(): float|int

CollectionInterface::median(): float|int

CollectionInterface::variance(): float|int

CollectionInterface::deviation(): float|int

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

Collection methods

Collection::append(mixed ...$value): static

Collection::prepend()

Collection::lazy(): CollectionInterface

LazyCollection methods