# Collection

GitHub

# Description

This package is inspired by the Laravel Collection Class. It is basically a wrapper around PHPs native array functions.

# Installation

This package is installed via composer. Simply run composer require mrcrmn/collection in your terminal. Don't forget to require composers generated autoloader.

# Basic Usage

There are two ways to instanciate a new Collection instance.

use mrcrmn\Colelction\Collection;

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

// or

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

After that you can use all of the available methods.

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

$collection->sum(); // 6

$collection->map(function($item) {
    return $item * 2;            // [2, 4, 6]
});

# Basic API

# set($key, $value = null)

Adds an element to the array. With key or without.

  • Arguments:

    • string $key
    • mixed|null $value

  • Returns: $this

  • Usage:

    $collection->set('key', 'value');
$collection->toArray(); // ['key' => 'value']

$collection2->set('value');
$collection2->toArray(); // ['value']

# get($key, $default = null)

Gets an element of the array by key. Returns the default if the key doesn't exist.

  • Arguments:

    • string $key
    • mixed|null $default

  • Returns: mixed

  • Usage:

    $collection->set('key', 'value');
$collection->get('key') // 'value'

$collection->get('unknown-key'); // null
$collection->get('unknown-key', 'default'); // 'default'

# remove($key)

Unsets an element of the array by a given key.

  • Arguments:

    • string|int $key

  • Returns: $this

  • Usage:

    $collection->remove('key');

# json()

  • Returns: string The JSON encoded array

  • Usage:

    $collection->json();

# count()

Returns the length of the array.

  • Returns: int

  • Usage:

    $collection->count();

# reverse($preserve = false)

  • Arguments:

    • bool $preserve Whether or not to preserve keys

  • Returns: $this But reversed

  • Usage:

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

$collection->reverse(); // [6, 1, 2]

# isEmpty()

Checks if the collection is empty.

  • Returns: bool

  • Usage:

    $collection = Collection::make();    

$collection->isEmpty(); // true
$collection->set('something');
$collection->isEmpty(); // false

# exists($key)

Checks if a given key exists.

  • Arguments:

    • string|int $key

  • Returns: bool

  • Usage:

    $collection = Collection::make(['key' => 'value']);    

$collection->exists('key'); // true
$collection->exists('something unrelated'); // false

# map($callback)

Runs the given callback on each element of the array.

  • Arguments:

    • Callable $callable The anonymous function to be applied to each item of the collection.

  • Returns: $this

  • Usage:

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

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

$mapped->toArray(); // [2, 4, 6]

# sum()

Returns the sum of all array elements.

  • Returns: int

  • Usage:

    $collection = Collection::make([1, 2, 3]);
    
$collection->sum(); // 6

# reduce($callback, $initial = null)

Reduces the array to a single value.

  • Arguments:

    • Callable $callback
    • mixed $initial

  • Returns: mixed

  • Usage:

    $collection = Collection::make([1, 2, 3, 4]);
    
$collection->reduce(function($carry, $number) {
    return $carry += $number;
}, 0); // 10

# filter($callback = null)

Filters the array by a given callback.

  • Arguments:

    • Callable|null $callback

  • Returns: $this

  • Usage:

    $collection = Collection::make([1, 2, 3]);
    
$filtered = $collection->filter(function($item) {
    return $item > 1;
});

$filtered->toArray(); // [2, 3]

# chunk($size)

Splits the array into chunks of the given size.

  • Arguments:

    • int $chunk

  • Returns: $this

  • Usage:

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

$chunked = $collection->chunk(2);

$chunked->toArray(); // [[1, 2], [3, 4], [5, 6]]

# slice($offset = 0, $length = 1, $preserveKeys = false)

Slices the array.

  • Arguments:

    • int $offset
    • int $length
    • bool $preserveKeys

  • Returns: $this

  • Usage:

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

$sliced = $collection->slice(1, 2);

$sliced->toArray(); // [2, 3]

# implode($glue = ', ')

Implodes the array using the given parameter as glue.

  • Arguments:

    • string $glue

  • Returns: string

  • Usage:

    Collection::make([1, 2, 3, 4])->implode('|'); // 1|2|3|4

# explode($delimiter, $string)

Explodes a string and returns a new Collection instance.

  • Arguments:

    • string $delimiter
    • string $string

  • Returns: $this

  • Usage:

    Collection::explode(',', '1,2,3,4'); // [1, 2, 3, 4]

# when($boolean, $callback)

Executes the given callback if the boolean is true.

  • Arguments:

    • bool $boolean
    • Callable $callback

  • Returns: $this

  • Usage:

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

$newCollection = $collection->when(true, function($c) {
    return $c->map(function($item) {
        return $item * 2;
    });
});  

$newCollection->toArray(); // [2, 4, 6]