amber / collection
Wrapper class for working with arrays.
Installs: 1 904
Dependents: 4
Suggesters: 0
Security: 0
Stars: 2
Watchers: 1
Forks: 0
Open Issues: 0
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
This package is auto-updated.
Last update: 2024-10-23 05:31:32 UTC
README
Collection
Data structures as an alternative to the array.
Usage
With composer
composer require amber/collection
In your code:
Use Amber\Collection\Collection;
- Instantiate an empty collection:
$collection = new Collection();
- Instantiate a collection for an array:
$array = ['key' => 'value']; $collection = new Collection($array);
- 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