hyqo/collection

1.0.0 2023-02-22 12:13 UTC

This package is auto-updated.

Last update: 2024-05-22 15:01:22 UTC


README

Packagist Version Packagist PHP Version Support GitHub Workflow Status

Basic collection with Generics support

example

Install

composer require hyqo/collection

Usage

For example, we have a Product class that we want to wrap in a collection:

class Product 
{
    public $title;
    public $amount;
    
    public function __construct(string $title, int $amount){
        $this->title = $title;
        $this->amount = $amount;
    }
}

Create a collection:

use \Hyqo\Collection\Collection;
use function \Hyqo\Collection\collect;

$collection = new Collection([new Product('foo', 10), new Product('bar', 2)]);
$collection = collect([new Product('foo', 10), new Product('bar', 2)]);

Auto-completion

There are three ways for code auto-completion:

1. Create a collection with items (not empty):

use Hyqo\Collection\Collection;

$collection = new Collection([new Product('foo', 10), new Product('bar', 2)]);

2. Use PHPDoc with Generics annotation:

use Hyqo\Collection\Collection;

/** @var Collection<Product> $collection */
$collection = new Collection();

3. Use your own class with @extends annotation:

use Hyqo\Collection\Collection;

/** @extends Collection<Product> */
class ProductCollection extends Collection 
{
}


$collection = new ProductCollection();

Now you have auto-completion (see the picture above)

Methods

add

function add($item): static

Add new item to a collection:

$collection->add($item);

get

function get(int $index): T|null

Get item of a collection by index:

$collection->get(0);

each

function each(callable $closure): static<T>

Pass each item to a closure:

$collection->each(function(Product $product) {
    // do something
});

map

function map(callable $closure): static<T>

Pass each item to a closure and create a new collection of results.

The closure must return a value of T or \Generator<T>:

$collection->map(function(Product $product) {
    // do something
    return $product;
});

reduce

function reduce(callable $closure, $initial = null): mixed|null

Reduces the collection to a single value:

$collection = new Collection([new Product('foo', 10), new Product('bar', 2)]);

$amount = $collection->reduce(function($carry, Product $product) {
    return $carry + $product->amount;
});

// 4

slice

function slice(int $first, ?int $length = null): static<T>

Create a new collection with a slice of the current one:

$collection->slice(3);

copy

function copy(): static<T>

Create a new collection with the same elements (alias for slice(0)):

$collection->copy();

chunk

function chunk(int $length): \Generator<static<T>>

Breaks the collection into multiple collections of a given length. The last one may contain fewer elements:

$collection->chunk(10);

filter

function filter(callable $closure): static<T>

Pass each item to a closure and create a new collection of items for which its result will be true.

The closure must return a bool value:

$collection->filter(function(Product $product){
    return $product->amount > 1;
});

toArray

function toArray(?callable $closure = null): array

Return all items of a collection. You can transform every element of array via a closure. If you need an associative array, the closure should return a generator yielding a key/value pair.

The closure must return any value or \Generator<array-key,mixed>:

$collection->toArray(); // [Product, Product]

$collection->toArray(function(Product $product) {
    return $product->title;
}); // ['foo', 'bar']

$collection->toArray(function(Product $product): \Generator {
    yield $product->title => $product->amount;
}); // ['foo'=>10, 'bar'=>2]