, (*1)
Collection Extension for Yii 2
The yii2mod\collection\Collection class provides a fluent, convenient wrapper for working with arrays of data., (*2)
, (*3)
Support us
Does your business depend on our contributions? Reach out and support us on Patreon.
All pledges will be dedicated to allocating workforce on maintenance and new awesome stuff., (*4)
Installation
The preferred way to install this extension is through composer., (*5)
Either run, (*6)
php composer.phar require --prefer-dist yii2mod/collection "*"
or add, (*7)
"yii2mod/collection": "*"
to the require section of your composer.json file., (*8)
Creating Collections
$collection = new Collection([1, 2, 3]);
// or via `make` function
$collection = Collection::make([1, 2, 3]);
Available Methods
Method Listing
all()
The all method simply returns the underlying array represented by the collection:, (*9)
$collection = new Collection([1, 2, 3]);
$collection->all();
// [1, 2, 3]
avg()
The avg method returns the average of all items in the collection:, (*10)
$collection = new Collection([1, 2, 3, 4, 5]);
$collection->avg();
// 3
If the collection contains nested arrays or objects, you should pass a key to use for determining which values to calculate the average:, (*11)
$collection = new Collection([
['id' => 1, 'price' => 150],
['id' => 2, 'price' => 250],
]);
$collection->avg('price');
// 200
chunk()
The chunk method breaks the collection into multiple, smaller collections of a given size:, (*12)
$collection = new Collection([1, 2, 3, 4, 5, 6, 7]);
$chunks = $collection->chunk(4);
$chunks->toArray();
// [[1, 2, 3, 4], [5, 6, 7]]
collapse()
The collapse method collapses a collection of arrays into a flat collection:, (*13)
$collection = new Collection([[1, 2, 3], [4, 5, 6], [7, 8, 9]]);
$collapsed = $collection->collapse();
$collapsed->all();
// [1, 2, 3, 4, 5, 6, 7, 8, 9]
combine()
Create a collection by using this collection for keys and another for its values:, (*14)
$collection = new Collection(['name', 'age']);
$combined = $collection->combine(['George', 29]);
$combined->all();
// ['name' => 'George', 'age' => 29]
contains()
The contains method determines whether the collection contains a given item:, (*15)
$collection = new Collection(['city' => 'Alabama', 'country' => 'USA']);
$collection->contains('Alabama');
// true
$collection->contains('New York');
// false
You may also pass a key / value pair to the contains method, which will determine if the given pair exists in the collection:, (*16)
$collection = new Collection([
['city' => 'Alabama'],
['city' => 'New York']
]);
$collection->contains('city', 'New York');
// true
count()
The count method returns the total number of items in the collection:, (*17)
$collection = new Collection([1, 2, 3, 4, 5]);
$collection->count();
// 5
diff()
The diff method compares the collection against another collection or a plain PHP array:, (*18)
$collection = new Collection([1, 2, 3, 4, 5]);
$diff = $collection->diff([2, 4, 6, 8]);
$diff->all();
// [1, 3, 5]
each()
The each method iterates over the items in the collection and passes each item to a given callback:, (*19)
$collection = $collection->each(function ($item, $key) {
if (/* some condition */) {
return false;
}
});
every()
The every method creates a new collection consisting of every n-th element:, (*20)
$collection = new Collection(['a', 'b', 'c', 'd', 'e', 'f']);
$collection->every(4);
// ['a', 'e']
You may optionally pass offset as the second argument:, (*21)
$collection->every(4, 1);
// ['b', 'f']
except()
Get all items except for those with the specified keys:, (*22)
$collection = new Collection(['id' => 1, 'name' => 'Desk', 'price' => 100, 'discount' => false]);
$filtered = $collection->except(['price', 'discount']);
$filtered->all();
// ['id' => 1, 'name' => 'Desk']
For the inverse of except, see the only method., (*23)
filter()
The filter method filters the collection by a given callback, keeping only those items that pass a given truth test:, (*24)
$collection = new Collection([1, 2, 3, 4]);
$filtered = $collection->filter(function ($value, $key) {
return $value > 2;
});
$filtered->all();
// [3, 4]
first()
The first method returns the first element in the collection that passes a given truth test:, (*25)
Collection::make([1, 2, 3, 4])->first(function ($key, $value) {
return $value > 2;
});
// 3
You may also call the first method with no arguments to get the first element in the collection. If the collection is empty, null is returned:, (*26)
$collection = new Collection([1, 2, 3, 4, 5]);
$collection->first();
// 1
last()
The last method returns the last element in the collection that passes a given truth test:, (*27)
Collection::make([1, 2, 3, 4])->last(function ($key, $value) {
return $value > 2;
});
// 4
You may also call the last method with no arguments to get the last element in the collection. If the collection is empty, null is returned:, (*28)
$collection = new Collection([1, 2, 3, 4, 5]);
$collection->last();
// 5
flatten()
The flatten method flattens a multi-dimensional collection into a single dimension:, (*29)
$collection = new Collection(['language' => 'java', 'languages' => ['php', 'javascript']]);
$collection->flatten();
// ['java', 'php', 'javascript']
flip()
The flip method swaps the collection's keys with their corresponding values:, (*30)
$collection = new Collection(['firstName' => 'Igor', 'lastName' => 'Chepurnoy']);
$collection->flip();
// ['Igor' => 'firstName', 'Chepurnoy' => 'lastName']
forget()
The forget method removes an item from the collection by its key:, (*31)
$collection = new Collection(['firstName' => 'Igor', 'lastName' => 'Chepurnoy']);
$collection->forget('firstName');
$collection->all();
// ['lastName' => 'Chepurnoy']
Unlike most other collection methods, forget does not return a new modified collection; it modifies the collection it is called on., (*32)
forPage()
The forPage method returns a new collection containing the items that would be present on a given page number:, (*33)
$collection = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9]);
$chunk = $collection->forPage(2, 3);
$chunk->all();
// [4, 5, 6]
The method requires the page number and the number of items to show per page, respectively., (*34)
get()
Get an item from the collection by key:, (*35)
$collection = new Collection([
'User' => [
'identity' => [
'id' => 1
]
]
]);
$collection->get('User.identity.id');
// 1
You may optionally pass a default value as the second argument:, (*36)
$collection->get('User.identity.email', false);
// false
groupBy()
The groupBy method groups the collection's items by a given key:, (*37)
$collection = new Collection([
['id' => 'id_2', 'name' => 'Bob'],
['id' => 'id_2', 'name' => 'John'],
['id' => 'id_3', 'name' => 'Frank'],
]);
$grouped = $collection->groupBy('id');
$grouped->toArray();
/*
[
'id_2' => [
['id' => 'id_2', 'name' => 'Bob'],
['id' => 'id_2', 'name' => 'John'],
],
'id_3' => [
['id' => 'id_3', 'name' => 'Frank'],
],
]
*/
In addition to passing a string key, you may also pass a callback. The callback should return the value you wish to key the group by:, (*38)
$grouped = $collection->groupBy(function ($item, $key) {
return substr($item['id'], -2);
});
/*
[
'_2' => [
['id' => 'id_2', 'name' => 'Bob'],
['id' => 'id_2', 'name' => 'John'],
],
'_3' => [
['id' => 'id_3', 'name' => 'Frank'],
],
]
*/
has()
The has method determines if a given key exists in the collection:, (*39)
$collection = new Collection(['id' => 1, 'name' => 'Igor']);
$collection->has('id');
// true
$collection->has('email');
// false
implode()
Concatenate values of a given key as a string:, (*40)
$collection = new Collection([
['account_id' => 1, 'name' => 'Ben'],
['account_id' => 2, 'name' => 'Bob'],
]);
$collection->implode('name', ', ');
// Ben, Bob
If the collection contains simple strings or numeric values, simply pass the "glue" as the only argument to the method:, (*41)
Collection::make(['Ben', 'Bob'])->implode(' and ')
// Ben and Bob
intersect()
The intersect method removes any values that are not present in the given array or collection:, (*42)
$collection = new Collection(['php', 'python', 'ruby']);
$intersect = $collection->intersect(['python', 'ruby', 'javascript']);
$intersect->all();
// [1 => 'python', 2 => 'ruby']
isEmpty()
The isEmpty method returns true if the collection is empty; otherwise, false is returned:, (*43)
$collection = (new Collection([]))->isEmpty();
// true
isNotEmpty()
The isNotEmpty method returns true if the collection is not empty; otherwise, false is returned:, (*44)
$collection = (new Collection([]))->isNotEmpty();
// false
keyBy()
Key an associative array by a field or using a callback:, (*45)
$collection = new Collection([
['product_id' => '100', 'name' => 'desk'],
['product_id' => '200', 'name' => 'chair'],
]);
$keyed = $collection->keyBy('product_id');
$keyed->all();
/*
[
'100' => ['product_id' => '100', 'name' => 'desk'],
'200' => ['product_id' => '200', 'name' => 'chair'],
]
*/
You may also pass your own callback, which should return the value to key the collection by:, (*46)
$collection = new Collection([
['product_id' => '100', 'name' => 'desk'],
['product_id' => '200', 'name' => 'chair'],
]);
$keyed = $collection->keyBy(function ($item) {
return strtoupper($item['name']);
});
$keyed->all();
/*
[
'DESK' => ['product_id' => '100', 'name' => 'desk'],
'CHAIR' => ['product_id' => '200', 'name' => 'chair'],
]
*/
keys()
The keys method returns all of the collection's keys:, (*47)
$collection = new Collection([
'city' => 'New York',
'country' => 'USA'
]);
$collection->keys();
// ['city', 'country']
map()
The map method iterates through the collection and passes each value to the given callback. The callback is free to modify the item and return it, thus forming a new collection of modified items:, (*48)
$collection = new Collection([1, 2, 3, 4, 5]);
$multiplied = $collection->map(function ($item, $key) {
return $item * 2;
});
$multiplied->all();
// [2, 4, 6, 8, 10]
Like most other collection methods, map returns a new collection instance; it does not modify the collection it is called on. If you want to transform the original collection, use the transform method., (*49)
max()
Get the max value of a given key:, (*50)
$collection = new Collection([['foo' => 10], ['foo' => 20]]);
$max = $collection->max('foo');
// 20
$collection = new Collection([1, 2, 3, 4, 5]);
$max = $collection->max();
// 5
merge()
Merge the collection with the given items:, (*51)
$collection = new Collection(['product_id' => 1, 'name' => 'Desk']);
$merged = $collection->merge(['price' => 100, 'discount' => false]);
$merged->all();
// ['product_id' => 1, 'name' => 'Desk', 'price' => 100, 'discount' => false]
min()
Get the min value of a given key:, (*52)
$collection = new Collection([['foo' => 10], ['foo' => 20]]);
$min = $collection->min('foo');
// 10
$collection = new Collection([1, 2, 3, 4, 5]);
$min = $collection->min();
// 1
only()
The only method returns the items in the collection with the specified keys:, (*53)
$collection = new Collection(['product_id' => 1, 'name' => 'Desk', 'price' => 100, 'discount' => false]);
$filtered = $collection->only(['product_id', 'name']);
$filtered->all();
// ['product_id' => 1, 'name' => 'Desk']
pluck()
The pluck method retrieves all of the collection values for a given key:, (*54)
$collection = new Collection([
['product_id' => 'prod-100', 'name' => 'Desk'],
['product_id' => 'prod-200', 'name' => 'Chair'],
]);
$plucked = $collection->pluck('name');
$plucked->all();
// ['Desk', 'Chair']
You may also specify how you wish the resulting collection to be keyed:, (*55)
$plucked = $collection->pluck('name', 'product_id');
$plucked->all();
// ['prod-100' => 'Desk', 'prod-200' => 'Chair']
pop()
The pop method removes and returns the last item from the collection:, (*56)
$collection = new Collection([1, 2, 3, 4, 5]);
$collection->pop();
// 5
$collection->all();
// [1, 2, 3, 4]
prepend()
The prepend method adds an item to the beginning of the collection:, (*57)
$collection = new Collection([1, 2, 3, 4, 5]);
$collection->prepend(0);
$collection->all();
// [0, 1, 2, 3, 4, 5]
You can optionally pass a second argument to set the key of the prepended item:, (*58)
$collection = Collection::make(['one' => 1, 'two' => 2]);
$collection->prepend(0, 'zero');
$collection->all();
// ['zero' => 0, 'one' => 1, 'two', => 2]
pull()
The pull method removes and returns an item from the collection by its key:, (*59)
$collection = new Collection(['product_id' => 'prod-100', 'name' => 'Desk']);
$collection->pull('name');
// 'Desk'
$collection->all();
// ['product_id' => 'prod-100']
push()
Push an item onto the end of the collection:, (*60)
$collection = new Collection([1, 2, 3, 4]);
$collection->push(5);
$collection->all();
// [1, 2, 3, 4, 5]
put()
Put an item in the collection by key:, (*61)
$collection = new Collection(['product_id' => 1, 'name' => 'Desk']);
$collection->put('price', 100);
$collection->all();
// ['product_id' => 1, 'name' => 'Desk', 'price' => 100]
random()
The random method returns a random item from the collection:, (*62)
$collection = new Collection([1, 2, 3, 4, 5]);
$collection->random();
// 4 - (retrieved randomly)
You may optionally pass an integer to random. If that integer is more than 1, a collection of items is returned:, (*63)
$random = $collection->random(3);
$random->all();
// [2, 4, 5] - (retrieved randomly)
reduce()
The reduce method reduces the collection to a single value, passing the result of each iteration into the subsequent iteration:, (*64)
$collection = new Collection([1, 2, 3]);
$total = $collection->reduce(function ($carry, $item) {
return $carry + $item;
});
// 6
The value for $carry on the first iteration is null; however, you may specify its initial value by passing a second argument to reduce:, (*65)
$collection->reduce(function ($carry, $item) {
return $carry + $item;
}, 4);
// 10
reject()
The reject method filters the collection using the given callback. The callback should return true for any items it wishes to remove from the resulting collection:, (*66)
$collection = new Collection([1, 2, 3, 4]);
$filtered = $collection->reject(function ($value, $key) {
return $value > 2;
});
$filtered->all();
// [1, 2]
reverse()
The reverse method reverses the order of the collection's items:, (*67)
$collection = new Collection([1, 2, 3, 4, 5]);
$reversed = $collection->reverse();
$reversed->all();
// [5, 4, 3, 2, 1]
search()
Search the collection for a given value and return the corresponding key if successful:, (*68)
$collection = new Collection([2, 4, 6, 8]);
$collection->search(4);
// 1
The search is done using a "loose" comparison. To use strict comparison, pass true as the second argument to the method:, (*69)
$collection->search('4', true);
// false
shift()
The shift method removes and returns the first item from the collection:, (*70)
$collection = new Collection([1, 2, 3, 4, 5]);
$collection->shift();
// 1
$collection->all();
// [2, 3, 4, 5]
shuffle()
Shuffle the items in the collection:, (*71)
$collection = new Collection([1, 2, 3, 4, 5]);
$shuffled = $collection->shuffle();
$shuffled->all();
// [3, 2, 5, 1, 4] // (generated randomly)
slice()
Slice the underlying collection array:, (*72)
$collection = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
$slice = $collection->slice(4);
$slice->all();
// [5, 6, 7, 8, 9, 10]
If you would like to limit the size of the returned slice, pass the desired size as the second argument to the method:, (*73)
$slice = $collection->slice(4, 2);
$slice->all();
// [5, 6]
sort()
Sort through each item with a callback:, (*74)
$collection = new Collection([5, 3, 1, 2, 4]);
$sorted = $collection->sort();
$sorted->values()->all();
// [1, 2, 3, 4, 5]
sortBy()
Sort the collection using the given callback:, (*75)
$collection = new Collection([
['name' => 'Desk', 'price' => 200],
['name' => 'Chair', 'price' => 100],
['name' => 'Bookcase', 'price' => 150],
]);
$sorted = $collection->sortBy('price');
$sorted->values()->all();
/*
[
['name' => 'Chair', 'price' => 100],
['name' => 'Bookcase', 'price' => 150],
['name' => 'Desk', 'price' => 200],
]
*/
You can also pass your own callback to determine how to sort the collection values:, (*76)
$collection = new Collection([
['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
['name' => 'Chair', 'colors' => ['Black']],
['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
]);
$sorted = $collection->sortBy(function ($product, $key) {
return count($product['colors']);
});
$sorted->values()->all();
/*
[
['name' => 'Chair', 'colors' => ['Black']],
['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
]
*/
sortByDesc()
This method has the same signature as the sortBy() method, but will sort the collection in the opposite order., (*77)
splice()
Splice a portion of the underlying collection array:, (*78)
$collection = new Collection([1, 2, 3, 4, 5]);
$chunk = $collection->splice(2);
$chunk->all();
// [3, 4, 5]
$collection->all();
// [1, 2]
You may pass a second argument to limit the size of the resulting chunk:, (*79)
$collection = new Collection([1, 2, 3, 4, 5]);
$chunk = $collection->splice(2, 1);
$chunk->all();
// [3]
$collection->all();
// [1, 2, 4, 5]
In addition, you can pass a third argument containing the new items to replace the items removed from the collection:, (*80)
$collection = new Collection([1, 2, 3, 4, 5]);
$chunk = $collection->splice(2, 1, [10, 11]);
$chunk->all();
// [3]
$collection->all();
// [1, 2, 10, 11, 4, 5]
sum()
Get the sum of the given values:, (*81)
$collection = new Collection([1, 2, 3]);
$collection->sum();
// 6
If the collection contains nested arrays or objects, you should pass a key to use for determining which values to sum:, (*82)
$collection = new Collection([
['name' => 'Books', 'countOfProduct' => 100],
['name' => 'Chairs', 'countOfProduct' => 200],
]);
$collection->sum('countOfProduct');
// 300
In addition, you may pass your own callback to determine which values of the collection to sum:, (*83)
$collection = new Collection([
['name' => 'Chair', 'colors' => ['Black']],
['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
]);
$collection->sum(function ($product) {
return count($product['colors']);
});
// 6
take()
Take the first or last {$limit} items:, (*84)
$collection = new Collection([0, 1, 2, 3, 4, 5]);
$chunk = $collection->take(3);
$chunk->all();
// [0, 1, 2]
You may also pass a negative integer to take the specified amount of items from the end of the collection:, (*85)
$collection = new Collection([0, 1, 2, 3, 4, 5]);
$chunk = $collection->take(-2);
$chunk->all();
// [4, 5]
toArray()
Get the collection of items as a plain array:, (*86)
$collection = new Collection('name');
$collection->toArray();
/*
['name']
*/
toArray() also converts all of its nested objects to an array. If you want to get the underlying array as is, use the all() method instead., (*87)
tap()
The tap method passes the collection to the given callback, allowing you to "tap" into the collection at a specific point and do something with the items while not affecting the collection itself:, (*88)
$collection = new Collection([2, 4, 3, 1, 5]);
$result = $collection->sort()
->tap(function ($collection) {
// Values after sorting
var_dump($collection->values()->toArray());
})
->shift();
// 1
toJson()
Get the collection of items as JSON:, (*89)
$collection = new Collection(['name' => 'Desk', 'price' => 200]);
$collection->toJson();
// '{"name":"Desk","price":200}'
Transform each item in the collection using a callback:, (*90)
$collection = new Collection([1, 2, 3, 4, 5]);
$collection->transform(function ($item, $key) {
return $item * 2;
});
$collection->all();
// [2, 4, 6, 8, 10]
Unlike most other collection methods, transform() modifies the collection itself. If you wish to create a new collection instead, use the map() method., (*91)
unique()
Return only unique items from the collection array:, (*92)
$collection = new Collection([1, 1, 2, 2, 3, 4, 2]);
$unique = $collection->unique();
$unique->values()->all();
// [1, 2, 3, 4]
The returned collection keeps the original array keys. In this example we used the values() method to reset the keys to consecutively numbered indexes., (*93)
When dealing with nested arrays or objects, you may specify the key used to determine uniqueness:, (*94)
$collection = new Collection([
['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'],
['name' => 'iPhone 5', 'brand' => 'Apple', 'type' => 'phone'],
['name' => 'Apple Watch', 'brand' => 'Apple', 'type' => 'watch'],
['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'],
['name' => 'Galaxy Gear', 'brand' => 'Samsung', 'type' => 'watch'],
]);
$unique = $collection->unique('brand');
$unique->values()->all();
/*
[
['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'],
['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'],
]
*/
You may also pass your own callback to determine item uniqueness:, (*95)
$unique = $collection->unique(function ($item) {
return $item['brand'].$item['type'];
});
$unique->values()->all();
/*
[
['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'],
['name' => 'Apple Watch', 'brand' => 'Apple', 'type' => 'watch'],
['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'],
['name' => 'Galaxy Gear', 'brand' => 'Samsung', 'type' => 'watch'],
]
*/
uniqueStrict()
This method has the same signature as the unique method; however, all values are compared using "strict" comparisons., (*96)
values()
Reset the keys on the underlying array:, (*97)
$collection = new Collection([
10 => ['product' => 'Desk', 'price' => 200],
11 => ['product' => 'Desk', 'price' => 200]
]);
$values = $collection->values();
$values->all();
/*
[
0 => ['product' => 'Desk', 'price' => 200],
1 => ['product' => 'Desk', 'price' => 200],
]
*/
where()
The where method filters the collection by a given key / value pair:, (*98)
$collection = new Collection([
['product' => 'Desk', 'price' => 200],
['product' => 'Chair', 'price' => 100],
['product' => 'Bookcase', 'price' => 150],
['product' => 'Door', 'price' => 100],
]);
$filtered = $collection->where('price', 100);
$filtered->all();
/*
[
['product' => 'Chair', 'price' => 100],
['product' => 'Door', 'price' => 100],
]
*/
The where() method uses strict comparisons when checking item values. Use the whereLoose method to filter using whereLoose() comparisons., (*99)
whereLoose()
This method has the same signature as the where() method; however, all values are compared using "loose" comparisons., (*100)
whereIn()
The whereIn method filters the collection by a given key / value contained within the given array., (*101)
$collection = new Collection([
['product' => 'Desk', 'price' => 200],
['product' => 'Chair', 'price' => 100],
['product' => 'Bookcase', 'price' => 150],
['product' => 'Door', 'price' => 100],
]);
$filtered = $collection->whereIn('price', [150, 200]);
$filtered->all();
/*
[
['product' => 'Bookcase', 'price' => 150],
['product' => 'Desk', 'price' => 200],
]
*/
The whereIn() method uses strict comparisons when checking item values. Use the whereInLoose() method to filter using "loose" comparisons., (*102)
whereInLoose()
This method has the same signature as the whereIn() method; however, all values are compared using "loose" comparisons., (*103)
zip()
The zip method merges together the values of the given array with the values of the collection at the corresponding index:, (*104)
$collection = new Collection(['Chair', 'Desk']);
$zipped = $collection->zip([100, 200]);
$zipped->all();
// [['Chair', 100], ['Desk', 200]]
Wallogit.com
