====== Collections ======

**Introduction**

The Illuminate\Support\Collection class provides a fluent, convenient wrapper for working with arrays of data. For example, check out the following code. We'll use the collect helper to create a new collection instance from the array, run the strtoupper function on each element, and then remove all empty elements:
<code>
$collection = collect(['taylor', 'abigail', null])->map(function ($name) {
    return strtoupper($name);
})->reject(function ($name) {
    return empty($name);
});
</code>
As you can see, the Collection class allows you to chain its methods to perform fluent mapping and reducing of the underlying array. In general, collections are immutable, meaning every Collection method returns an entirely new Collection instance.

**Creating Collections**

As mentioned above, the collect helper returns a new Illuminate\Support\Collection instance for the given array. So, creating a collection is as simple as:

<code>$collection = collect([1, 2, 3]);</code>

**Extending Collections**

Collections are "macroable", which allows you to add additional methods to the Collection class at run time. The Illuminate\Support\Collection class' macro method accepts a closure that will be executed when your macro is called. The macro closure may access the collection's other methods via $this, just as if it were a real method of the collection class. For example, the following code adds a toUpper method to the Collection class:
<code>
use Illuminate\Support\Collection;
use Illuminate\Support\Str;

Collection::macro('toUpper', function () {
    return $this->map(function ($value) {
        return Str::upper($value);
    });
});

$collection = collect(['first', 'second']);

$upper = $collection->toUpper();

// ['FIRST', 'SECOND']
</code>
Typically, you should declare collection macros in the boot method of a service provider.


**Macro Arguments**

If necessary, you may define macros that accept additional arguments:

<code>
use Illuminate\Support\Collection;
use Illuminate\Support\Facades\Lang;
use Illuminate\Support\Str;

Collection::macro('toLocale', function ($locale) {
    return $this->map(function ($value) use ($locale) {
        return Lang::get($value, $locale);
    });
});

$collection = collect(['first', 'second']);

$translated = $collection->toLocale('es');
</code>

**Available Methods**

For the majority of the remaining collection documentation, we'll discuss each method available on the Collection class. Remember, all of these methods may be chained to fluently manipulate the underlying array. Furthermore, almost every method returns a new Collection instance, allowing you to preserve the original copy of the collection when necessary:


all

average

avg

chunk

chunkWhile

collapse

collect

combine


concat

contains

containsStrict

count

countBy

crossJoin

dd

diff



diffAssoc

diffKeys

dump

duplicates

duplicatesStrict

each

eachSpread

every

except

filter

first

firstWhere

flatMap

flatten

flip

forget


forPage

get

groupBy

has

implode

intersect

intersectByKeys

isEmpty

isNotEmpty

join

keyBy

keys

last

macro

make

map


mapInto


mapSpread

mapToGroups

mapWithKeys


max

median

merge


mergeRecursive

min

mode

nth

only

pad

partition

pipe

pipeInto

pluck

pop

prepend

pull

push

put

random

reduce

reject

replace

replaceRecursive

reverse

search



shift

shuffle

skip

skipUntil

skipWhile

slice

some

sort

sortBy

sortByDesc

sortDesc

sortKeys

sortKeysDesc

splice

split

splitIn

sum

take


takeUntil

takeWhile

tap

times

toArray

toJson

transform


union

unique

uniqueStrict

unless

unlessEmpty


unlessNotEmpty

unwrap

values

when

whenEmpty

whenNotEmpty

where

whereStrict

whereBetween


whereIn


whereInStrict

whereInstanceOf

whereNotBetween

whereNotIn

whereNotInStrict

whereNotNull

whereNull

wrap

zip