hectororm/collection

v1.0.0-beta5 2022-09-05 09:14 UTC

This package is auto-updated.

Last update: 2022-11-05 09:32:19 UTC


README

Latest Version Software license Build Status Quality Grade Total Downloads

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.