# 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]