amber/collection

Wrapper class for working with arrays.

v0.6.9-beta 2020-01-20 16:01 UTC

Requires

• php: >=7.2.0

Requires (Dev)

• doctrine/collections: ^1.5
• lavoiesl/php-benchmark: ^1.4
• php-coveralls/php-coveralls: ^2.1
• tightenco/collect: ^5.7

GPL-3.0-or-later

• Deivi Peña

README

Collection

Data structures as an alternative to the array.

Usage

With composer

composer require amber/collection

In your code:

Use Amber\Collection\Collection;

1. Instantiate an empty collection:

$collection = new Collection();

1. Instantiate a collection for an array:

$array = ['key' => 'value'];

$collection = new Collection($array);

1. Or use the static factory method make():

$collection = Collection::make();

...

$array = ['key' => 'value'];

$collection = Collection::make($array);

Available methods

• has
• contains
• hasNot
• put
• add
• insert
• update
• push
• pushTo
• get
• find
• first
• last
• remove
• delete
• map
• filter
• sort
• reverse
• merge
• chunk
• column
• flip
• setMultiple
• getMultiple
• hasMultiple
• select
• where
• whereNot
• whereIn
• whereNotIn
• orderBy
• groupBy
• join
• sum
• firstOrNew
• updateOrNew

has()

Whether an item is present it the collection.

has(string $key) : boolean

$collection->set('name', 'Amber');

$collection->has('name'); // returns true.

$collection->has('other'); // returns false.

contains()

Alias for has.

contains(string $key) : boolean

hasNot()

Whether an item is not present it the collection.

hasNot(string $key) : boolean

$collection->set('name', 'Amber');

$collection->hasNot('name'); // returns false.

$collection->hasNot('other'); // returns true.

set()

Sets or updates an item in the collection.

set(string $key, mixed $value) : void

$collection->set('name', 'Amber');

$collection->has('name'); // returns true.

put()

Alias for set.

put(string $key, mixed $value) : void

add()

Sets a new item to the collection.

add(string $key, mixed $value) : boolean

$collection->add('name', 'Amber'); // returns true.

$collection->add('name', 'Amber'); // returns false, since the item already exists.

insert()

Alias for add.

insert(string $key, mixed $value) : boolean

update()

Updates an existent item in the collection.

update(string $key, mixed $value) : boolean

$collection->update('name', 'Amber'); // returns false, since the item doesn't exists in the collecction

$collection->set('name', 'Amber');

$collection->update('name', 'Collection'); // returns true.

push()

Sets a new item at the end of the collection.

push(mixed $value) : void

$collection->push('apple');
$collection->push('orange');
$collection->push('grapes');

$collection->all(); // returns ['apple', 'orange', 'grapes']

pushTo()

Push a new item at the end of a item in the collection.

pushTo(string $key, mixed $value) : boolean

$collection->set('colors', []); // Sets an empty array
$collection->pushTo('colors', 'red');
$collection->pushTo('colors', 'blue');
$collection->pushTo('colors', 'green');

$collection->get('colors'); // returns ['red', 'blue', 'green']

get()

Gets an item from collection.

get(string $key) : mixed|void

$collection->set('name', 'Amber');

$collection->get('name'); // returns 'Amber'

find()

Alias for get.

find(string $key) : mixed

first()

Returns the first element of the collection.

first() : mixed

$collection->push('apple');
$collection->push('orange');
$collection->push('grapes');

$collection->first(); // returns 'apple'

last()

Returns the last element of the collection.

last() : mixed

$collection->push('apple');
$collection->push('orange');
$collection->push('grapes');

$collection->last(); // returns 'grapes'

remove()

Deletes and retrives an item from collection.

remove(string $key) : mixed

$collection->set('name', 'Amber');

$name = $collection->remove('name');

$collection->has('name'); // returns false

echo $name; // prints 'Amber'

delete()

Deletes an item from collection.

delete(string $key) : boolean

$collection->set('name', 'Amber');

$collection->delete('name'); // returns true

$collection->delete('name'); // returns false, since the items was aleady deleted

map()

Iterates through the collection and passes each value to the given callback.

map(\Closure $callback) : \Amber\Collection\Base\Collection

$collection->push('apple');
$collection->push('orange');
$collection->push('grapes');

$maped = $collection->map(function ($value) {
    return ucfirst($value);
});

$maped->all(); // returns ['Apple', 'Orange', 'Grapes']

filter()

Returns a new filtered collection using a user-defined function.

filter(\Closure $callback) : \Amber\Collection\Base\Collection

$collection->push('apple');
$collection->push('orange');
$collection->push('grapes');

$filtered = $collection->filter(function ($value) {
    return $value == 'apple';
});

$filtered->all(); // returns ['apple']

sort()

Returns a new sorted collection using a user-defined comparison function.

sort(\Closure $callback) : \Amber\Collection\Base\Collection

$collection->push(3);
$collection->push(5);
$collection->push(2);

$sorted = $collection->filter(function ($a, $b) {
    return $a <=> $b;
});

$sorted->all(); // returns [2, 3, 5]

reverse()

Returns a new reversed collection.

reverse() : \Amber\Collection\Base\Collection

$collection->push(1);
$collection->push(2);
$collection->push(3);

$reversed = $collection->reverse();

$reversed->all() // returns [3, 2, 1]

merge()

Returns a new collection merged with one or more arrays.

merge(array $array) : \Amber\Collection\Base\Collection

$collection->push(1);
$collection->push(2);
$collection->push(3);

$collection->all(); // returns [1, 2, 3]

$array = [4, 5, 6];

$merged = $collection->merge($array);

$merged->all() // returns [1, 2, 3, 4, 5, 6]

chunk()

Splits an array into chunks.

chunk(integer $size, boolean $preserve_keys = false) : \Amber\Collection\Base\Collection

column()

Returns the values from a single column.

column(string $column) : \Amber\Collection\Base\Collection

$collection->push(['id' => '1', 'color' => 'red', 'name' => 'Fire']);
$collection->push(['id' => '2', 'color' => 'blue', 'name' => 'Sea']);
$collection->push(['id' => '3', 'color' => 'green', 'name' => 'Forest']);

$colors = $collection->column('color');

$colors->all(); // returns ['red', 'blue', 'green']

flip()

Exchanges all keys with their associated values.

flip() : \Amber\Collection\Base\Collection

$collection->set('color' => 'red');

$fliped = $collection->flip();

$fliped->all(); // returns ['red' => 'color']

setMultiple()

Sets or updates an array of items in the collection, and returns true on success.

setMultiple(array $array) : void

getMultiple()

Gets multiple items from the collection.

getMultiple(array $array) : mixed

hasMultiple()

Whether multiple items are present in the collection.

hasMultiple(array $array) : boolean

select()

Returns a new Collection containing the items in the specified column(s).

select(array|string $columns) : \Amber\Collection\Base\Collection

$collection->push(['id' => '1', 'color' => 'red', 'name' => 'Fire']);
$collection->push(['id' => '2', 'color' => 'blue', 'name' => 'Sea']);
$collection->push(['id' => '3', 'color' => 'green', 'name' => 'Forest']);

$items = $collection->select('id', 'color');

$items->all(); // returns [[1, 'red'], [2, 'blue'], [3, 'green']]

where()

Returns a new Collection containing the items in the specified column that are equal to the especified value.

where(string $column, mixed $value) : \Amber\Collection\Base\Collection

$collection->push(['id' => '1', 'color' => 'red', 'name' => 'Fire']);
$collection->push(['id' => '2', 'color' => 'blue', 'name' => 'Sea']);
$collection->push(['id' => '3', 'color' => 'green', 'name' => 'Forest']);

$filtered = $collection->where('color', 'red');

$filtered->all(); // returns ['id' => '1', 'color' => 'red', 'name' => 'Fire']

whereNot()

Returns a new Collection containing the items in the specified column that are not equal to the especified value.

whereNot(string $column, mixed $value) : \Amber\Collection\Base\Collection

$collection->push(['id' => '1', 'color' => 'red', 'name' => 'Fire']);
$collection->push(['id' => '2', 'color' => 'blue', 'name' => 'Sea']);
$collection->push(['id' => '3', 'color' => 'green', 'name' => 'Forest']);

$filtered = $collection->whereNot('color', 'red');

$filtered->all();
// returns [
    ['id' => '2', 'color' => 'blue', 'name' => 'Sea'],
    ['id' => '3', 'color' => 'green', 'name' => 'Forest']
]

whereIn()

Returns a new Collection containing the items in the specified column that are equal to the especified value(s).

whereIn(string $column, array $values = array()) : \Amber\Collection\Base\Collection

$collection->push(['id' => '1', 'color' => 'red', 'name' => 'Fire']);
$collection->push(['id' => '2', 'color' => 'blue', 'name' => 'Sea']);
$collection->push(['id' => '3', 'color' => 'green', 'name' => 'Forest']);

$filtered = $collection->whereIn('color', ['blue', 'green']);

$filtered->all();
// returns [
    ['id' => '2', 'color' => 'blue', 'name' => 'Sea'],
    ['id' => '3', 'color' => 'green', 'name' => 'Forest']
]

whereNotIn()

Returns a new Collection containing the items in the specified column that are not equal to the especified value(s).

whereNotIn(string $column, array $values = array()) : \Amber\Collection\Base\Collection

$collection->push(['id' => '1', 'color' => 'red', 'name' => 'Fire']);
$collection->push(['id' => '2', 'color' => 'blue', 'name' => 'Sea']);
$collection->push(['id' => '3', 'color' => 'green', 'name' => 'Forest']);

$filtered = $collection->whereNotIn('color', ['blue', 'green']);

$filtered->all(); // returns ['id' => '1', 'color' => 'red', 'name' => 'Fire']

orderBy()

Returns a new Collection containing the items ordered by the especified column.

orderBy(string $column, string $order = 'ASC') : \Amber\Collection\Base\Collection

$collection->push(['id' => '1', 'color' => 'red', 'name' => 'Fire']);
$collection->push(['id' => '2', 'color' => 'blue', 'name' => 'Sea']);
$collection->push(['id' => '3', 'color' => 'green', 'name' => 'Forest']);

$asc = $collection->orderBy('color');

$asc->all();
// returns [
    ['id' => '2', 'color' => 'blue', 'name' => 'Sea'],
    ['id' => '3', 'color' => 'green', 'name' => 'Forest'],
    ['id' => '1', 'color' => 'red', 'name' => 'Fire']
]

$desc = $collection->orderBy('color', 'desc'); // The $order param is not case sensitive.

$desc->all();
// returns [
    ['id' => '1', 'color' => 'red', 'name' => 'Fire'],
    ['id' => '3', 'color' => 'green', 'name' => 'Forest'],
    ['id' => '2', 'color' => 'blue', 'name' => 'Sea']   
]

groupBy()

Returns a new Collection grouped by the specified column.

groupBy(string $column) : \Amber\Collection\Base\Collection

$collection->push(['id' => '1', 'color' => 'red', 'name' => 'Fire']);
$collection->push(['id' => '2', 'color' => 'blue', 'name' => 'Sea']);
$collection->push(['id' => '3', 'color' => 'green', 'name' => 'Forest']);

$grouped = $collection->groupBy('color');

$grouped->all();
// returns [
    'red' => ['id' => '1', 'color' => 'red', 'name' => 'Fire'],
    'blue' => ['id' => '2', 'color' => 'blue', 'name' => 'Sea'],
    'green' => ['id' => '3', 'color' => 'green', 'name' => 'Forest']
]

join()

Returns a new Collection joined by the specified column.

join(array $array, string $pkey, string $fkey) : \Amber\Collection\Base\Collection

sum()

Calculates the sum of values in the collection.

sum(string $column = null) : integer

$collection->push(2);
$collection->push(5);
$collection->push(3);

$collection->sum(); // returns 10

Or you can sum a specific colum

$collection->push(['id' => 1, 'name' => 'red', 'quantity' => 2]);
$collection->push(['id' => 2, 'name' => 'blue', 'quantity' => 5]);
$collection->push(['id' => 3, 'name' => 'green', 'quantity' => 3]);

$collection->sum('quantity'); // returns 10

firstOrNew()

Gets the first item of the Collection or adds and returns a new one.

firstOrNew(string $key, mixed $value) : mixed

updateOrNew()

Updates an item from the Collection or adds a new one.

updateOrNew(string $key, mixed $value) : mixed