# Collections

<!-- -->

Mantle includes [Laravel's collections package](https://laravel.com/docs/master/collections) with support for all of its methods and with some special customizations to make it easier to work with WordPress. For example, you can pass a `WP_Query` object to the `collect` helper function and it will automatically convert it to a collection of `WP_Post` objects.

## Usage[​](#usage "Direct link to Usage")

You can use the `collect` helper function to create a new collection from an array or an object. You can also use the `collect` method on any collection instance to create a new collection from the items in the original collection.

```php
use function Mantle\Support\Helpers\collect;

$collection = collect( [ 1, 2, 3 ] );

```

You can then use any of the methods available on the collection instance to manipulate the items in the collection.

```php
use function Mantle\Support\Helpers\collect;

$collection = collect( [ 1, 2, 3 ] )->map( function( $item ) {
    return $item * 2;
} );

```

Collections can be treated like arrays, so you can use array accessors to get items from the collection.

```php
use function Mantle\Support\Helpers\collect;

$collection = collect( [ 1, 2, 3 ] );

$item = $collection[0]; // 1

```

## Available Methods[​](#available-methods "Direct link to Available Methods")

* [add](#add)
* [after](#after)
* [all](#all)
* [avg](#avg)
* [average](#average)
* [before](#before)
* [chunk](#chunk)
* [chunk\_while](#chunk_while)
* [collapse](#collapse)
* [collect](#collect)
* [combine](#combine)
* [concat](#concat)
* [contains](#contains)
* [contains\_one\_item](#contains_one_item)
* [contains\_strict](#contains_strict)
* [count](#count)
* [count\_by](#count_by)
* [cross\_join](#cross_join)
* [dd](#dd)
* [diff](#diff)
* [diff\_assoc](#diff_assoc)
* [diff\_assoc\_using](#diff_assoc_using)
* [diff\_keys](#diff_keys)
* [doesnt\_contain](#doesnt_contain)
* [dump](#dump)
* [duplicates](#duplicates)
* [duplicates\_strict](#duplicates_strict)
* [each](#each)
* [each\_spread](#each_spread)
* [empty](#empty)
* [every](#every)
* [except](#except)
* [filter](#filter)
* [first](#first)
* [first\_or\_fail](#first_or_fail)
* [first\_where](#first_where)
* [flat\_map](#flat_map)
* [flatten](#flatten)
* [flip](#flip)
* [for\_page](#for_page)
* [forget](#forget)
* [get](#get)
* [get\_caching\_iterator](#get_caching_iterator)
* [group\_by](#group_by)
* [has](#has)
* [implode](#implode)
* [implode\_str](#implode_str)
* [intersect](#intersect)
* [intersect\_assoc](#intersect_assoc)
* [intersect\_by\_keys](#intersect_by_keys)
* [is\_empty](#is_empty)
* [is\_not\_empty](#is_not_empty)
* [join](#join)
* [key\_by](#key_by)
* [keys](#keys)
* [last](#last)
* [make](#make)
* [map](#map)
* [map\_into](#map_into)
* [map\_spread](#map_spread)
* [map\_to\_dictionary](#map_to_dictionary)
* [map\_to\_groups](#map_to_groups)
* [map\_with\_keys](#map_with_keys)
* [max](#max)
* [median](#median)
* [merge](#merge)
* [merge\_recursive](#merge_recursive)
* [min](#min)
* [mode](#mode)
* [nth](#nth)
* [only](#only)
* [only\_children](#only_children)
* [pad](#pad)
* [partition](#partition)
* [pipe](#pipe)
* [pipe\_into](#pipe_into)
* [pipe\_through](#pipe_through)
* [pluck](#pluck)
* [pop](#pop)
* [prepend](#prepend)
* [prepend\_many](#prepend_many)
* [pull](#pull)
* [push](#push)
* [put](#put)
* [random](#random)
* [reduce](#reduce)
* [reduce\_spread](#reduce_spread)
* [reject](#reject)
* [replace](#replace)
* [replace\_recursive](#replace_recursive)
* [reverse](#reverse)
* [search](#search)
* [shift](#shift)
* [shuffle](#shuffle)
* [skip](#skip)
* [skip\_until](#skip_until)
* [skip\_while](#skip_while)
* [slice](#slice)
* [sliding](#sliding)
* [sole](#sole)
* [some](#some)
* [sort](#sort)
* [sort\_by](#sort_by)
* [sort\_by\_desc](#sort_by_desc)
* [sort\_desc](#sort_desc)
* [sort\_keys](#sort_keys)
* [sort\_keys\_desc](#sort_keys_desc)
* [sort\_keys\_using](#sort_keys_using)
* [splice](#splice)
* [split](#split)
* [split\_in](#split_in)
* [sum](#sum)
* [take](#take)
* [take\_until](#take_until)
* [take\_while](#take_while)
* [tap](#tap)
* [times](#times)
* [to\_array](#to_array)
* [to\_base](#to_base)
* [to\_json](#to_json)
* [to\_pretty\_json](#to_pretty_json)
* [toArray](#toarray)
* [transform](#transform)
* [trim](#trim)
* [undot](#undot)
* [unique](#unique)
* [unique\_strict](#unique_strict)
* [unless\_empty](#unless_empty)
* [unless\_not\_empty](#unless_not_empty)
* [unwrap](#unwrap)
* [values](#values)
* [when\_empty](#when_empty)
* [when\_not\_empty](#when_not_empty)
* [where](#where)
* [where\_between](#where_between)
* [where\_in](#where_in)
* [where\_in\_strict](#where_in_strict)
* [where\_instance\_of](#where_instance_of)
* [where\_not\_between](#where_not_between)
* [where\_not\_in](#where_not_in)
* [where\_not\_in\_strict](#where_not_in_strict)
* [where\_not\_null](#where_not_null)
* [where\_null](#where_null)
* [where\_strict](#where_strict)
* [wrap](#wrap)
* [zip](#zip)

### add[​](#add "Direct link to add")

The `add` method adds an item to the collection.

```php
$collection = collect( [ 1, 2, 3 ] )->add( 4 );

```

### after[​](#after "Direct link to after")

Get the item after the given item in the collection. You can pass a value or a callback to determine the target item. Returns null if the item is the last in the collection or not found.

```php
$collection = collect( [ 'a', 'b', 'c', 'd' ] );
$after = $collection->after( 'b' ); // 'c'

$after = $collection->after( function( $item ) {
    return $item === 'c';
} ); // 'd'

```

### all[​](#all "Direct link to all")

The `all` method gets all of the items in the collection.

```php
$items = collect( [ 1, 2, 3 ] )->all();

```

### avg[​](#avg "Direct link to avg")

Get the average value of a given key.

```php
$average = collect( [ 1, 2, 3 ] )->average();

$average = collect( [
    [ 'name' => 'John', 'age' => 30 ],
    [ 'name' => 'Jane', 'age' => 25 ],
] )->average( 'age' );

```

### average[​](#average "Direct link to average")

Alias for the `avg` method.

### before[​](#before "Direct link to before")

Get the item before the given item in the collection. You can pass a value or a callback to determine the target item. Returns null if the item is the first in the collection or not found.

```php
$collection = collect( [ 'a', 'b', 'c', 'd' ] );
$before = $collection->before( 'c' ); // 'b'

$before = $collection->before( function( $item ) {
    return $item === 'b';
} ); // 'a'

```

### chunk[​](#chunk "Direct link to chunk")

Chunk the collection into smaller collections of a given size.

```php
$chunks = collect( [ 1, 2, 3, 4, 5 ] )->chunk( 2 );
// [[1, 2], [3, 4], [5]]

```

### chunk\_while[​](#chunk_while "Direct link to chunk_while")

Chunk the collection into groups as long as the given callback returns true. Each group will contain consecutive items until the callback returns false.

```php
$chunks = collect( [1, 2, 3, 4, 5] )->chunk_while( function( $value, $key, $chunk ) {
    return $value - $chunk->last() <= 1;
} );
// [[1, 2, 3], [4, 5]]

```

### collapse[​](#collapse "Direct link to collapse")

Collapse the collection of arrays into a single, flat collection.

```php
$collection = collect( [ [ 1, 2, 3 ], [ 4, 5, 6 ] ] )->collapse();

// [1, 2, 3, 4, 5, 6]

```

### collect[​](#collect "Direct link to collect")

Convert the collection to a base Mantle collection instance. Useful if you are working with a subclass and want a plain collection.

```php
$base = $collection->collect();

```

### combine[​](#combine "Direct link to combine")

Combine the values of the collection with the values of another array or collection.

```php
$collection = collect( [ 'name', 'age' ] )->combine( [ 'John', 30 ] );
// ['name' => 'John', 'age' => 30]

```

### concat[​](#concat "Direct link to concat")

Concatenate values of the given array or collection to the collection.

```php
$collection = collect( [ 1, 2, 3 ] )->concat( [ 4, 5, 6 ] );
// [1, 2, 3, 4, 5, 6]

```

### contains[​](#contains "Direct link to contains")

Determine if the collection contains a given item.

```php
$contains = collect( [ 1, 2, 3 ] )->contains( 2 ); // true

```

### contains\_one\_item[​](#contains_one_item "Direct link to contains_one_item")

Determine if the collection contains only one item.

```php
$containsOneItem = collect( [ 1 ] )->contains_one_item(); // true

```

### contains\_strict[​](#contains_strict "Direct link to contains_strict")

Determine if the collection contains a given key / value pair.

```php
$contains = collect( [ 'name' => 'John' ] )->contains_strict( 'name', 'John' ); // true

```

### count[​](#count "Direct link to count")

Get the number of items in the collection.

```php
$count = collect( [ 1, 2, 3 ] )->count(); // 3

```

### count\_by[​](#count_by "Direct link to count_by")

Count the occurrences of values in the collection.

```php
$counts = collect( [ 1, 2, 2, 3, 3, 3 ] )->count_by();
// [1 => 1, 2 => 2, 3 => 3]

```

### cross\_join[​](#cross_join "Direct link to cross_join")

Cross join with the given lists, returning all possible permutations.

```php
$collection = collect( [ 1, 2 ] )->cross_join( [ 'a', 'b' ] );

```

### dd[​](#dd "Direct link to dd")

Dump the collection and end the script execution.

```php
collect( [ 1, 2, 3 ] )->dd();

```

### diff[​](#diff "Direct link to diff")

Compare the collection against another item or items using strict comparison.

```php
$diff = collect( [ 1, 2, 3 ] )->diff( [ 2, 3, 4 ] );
// [0 => 1]

```

### diff\_assoc[​](#diff_assoc "Direct link to diff_assoc")

Diff the collection with the given items, key and value-wise.

```php
$diff = collect( [ 'name' => 'John' ] )->diff_assoc( [ 'name' => 'Jane' ] );
// ['name' => 'John']

```

### diff\_assoc\_using[​](#diff_assoc_using "Direct link to diff_assoc_using")

Diff the collection with the given items, using a callback to compute the difference.

```php
$diff = collect( [ 'name' => 'John' ] )->diff_assoc_using( [ 'name' => 'Jane' ], function( $a, $b ) {
    return $a === $b;
} );
// ['name' => 'John']

```

### diff\_keys[​](#diff_keys "Direct link to diff_keys")

Diff the collection with the given items, key-wise.

```php
$diff = collect( [ 'name' => 'John' ] )->diff_keys( [ 'name' => 'Jane' ] );

```

### doesnt\_contain[​](#doesnt_contain "Direct link to doesnt_contain")

Determine if the collection does not contain a given key / value pair.

```php
$doesntContain = collect( [ 'name' => 'John' ] )->doesnt_contain( 'name', 'Jane' ); // true

```

### dump[​](#dump "Direct link to dump")

Dump the collection.

```php
collect( [ 1, 2, 3 ] )->dump();

```

### duplicates[​](#duplicates "Direct link to duplicates")

Get the items in the collection that have duplicate values.

```php
$duplicates = collect( [ 1, 2, 2, 3, 3, 3 ] )->duplicates();
// [2, 3]

```

### duplicates\_strict[​](#duplicates_strict "Direct link to duplicates_strict")

Get the items in the collection that have duplicate values.

```php
$duplicates = collect( [ 1, 2, 2, 3, 3, 3 ] )->duplicates_strict();
// [2, 3]

```

### each[​](#each "Direct link to each")

Iterate over the items in the collection.

```php
collect( [ 1, 2, 3 ] )->each( function( $item ) {
    // ...
} );

```

### each\_spread[​](#each_spread "Direct link to each_spread")

Iterate over the collection's items, passing each nested item value into the given callback:

```php
collect( [ [ 'John', 30 ], [ 'Jane', 25 ] ] )->each_spread( function( $name, $age ) {
    // ...
} );

```

### empty[​](#empty "Direct link to empty")

Create a new, empty collection instance.

```php
$empty = Collection::empty();

```

### every[​](#every "Direct link to every")

Determine if all items in the collection pass the given truth test.

```php
$every = collect( [ 1, 2, 3 ] )->every( function( $item ) {
    return $item > 0;
} );

```

### except[​](#except "Direct link to except")

Get all items except for those with the specified keys.

```php
$collection = collect( [ 'name' => 'John', 'age' => 30 ] )->except( 'age' );
// ['name' => 'John']

```

### filter[​](#filter "Direct link to filter")

Filter the items in the collection using the given callback.

```php
$collection = collect( [ 1, 2, 3 ] )->filter( function( $item ) {
    return $item > 1;
} );

```

### first[​](#first "Direct link to first")

Get the first item from the collection.

```php
$item = collect( [ 1, 2, 3 ] )->first();

```

### first\_or\_fail[​](#first_or_fail "Direct link to first_or_fail")

Get the first item in the collection that passes the given test, or throw an exception if no matching item is found.

```php
use Mantle\Support\Item_Not_Found_Exception;

try {
    $item = collect( [1, 2, 3] )->first_or_fail( fn( $item ) => $item > 2 );
} catch ( Item_Not_Found_Exception $e ) {
    // Handle not found
}

```

### first\_where[​](#first_where "Direct link to first_where")

Get the first item from the collection where the given key / value pair is true.

```php
$item = collect( [ 'name' => 'John', 'age' => 30 ] )->first_where( 'age', '>', 25 );

```

### flat\_map[​](#flat_map "Direct link to flat_map")

Map a collection and flatten the result by a single level.

```php
$collection = collect( [ [ 1, 2 ], [ 3, 4 ] ] )->flat_map( function( array $values ) {
    return array_map( function( $value ) {
        return $value * 2;
    }, $values );
} );

```

### flatten[​](#flatten "Direct link to flatten")

Flatten a multi-dimensional collection into a single dimension.

```php
$collection = collect( [ [ 1, 2 ], [ 3, 4 ] ] )->flatten();

```

### flip[​](#flip "Direct link to flip")

Flip the items in the collection.

```php
$collection = collect( [ 'name' => 'John', 'age' => 30 ] )->flip();

```

### for\_page[​](#for_page "Direct link to for_page")

Get a new collection containing the items for a given page.

```php
$collection = collect( [ 1, 2, 3, 4, 5 ] )->for_page( 2, 2 );
// [3, 4]

```

### forget[​](#forget "Direct link to forget")

Remove an item from the collection by key.

```php
$collection = collect( [ 'name' => 'John', 'age' => 30 ] )->forget( 'age' );

```

### get[​](#get "Direct link to get")

Get an item from the collection.

```php
$item = collect( [ 'name' => 'John', 'age' => 30 ] )->get( 'name' );

```

### get\_caching\_iterator[​](#get_caching_iterator "Direct link to get_caching_iterator")

Get a CachingIterator instance for the collection, which can be useful for advanced iteration scenarios.

```php
$iterator = collect( [1, 2, 3] )->get_caching_iterator();

```

### group\_by[​](#group_by "Direct link to group_by")

Group an associative array by a field or using a callback.

```php
$collection = collect( [
    [ 'name' => 'John', 'age' => 30 ],
    [ 'name' => 'Jane', 'age' => 25 ],
] )->group_by( 'age' );

```

### has[​](#has "Direct link to has")

Determine if an item exists in the collection by key.

```php
$has = collect( [ 'name' => 'John', 'age' => 30 ] )->has( 'name' );

```

### implode[​](#implode "Direct link to implode")

Join the items in the collection.

```php
$joined = collect( [ 'name', 'age' ] )->implode( ', ' );

```

### implode\_str[​](#implode_str "Direct link to implode_str")

Join the items in the collection into a string and return a Stringable instance.

```php
$string = collect( [ 'a', 'b', 'c' ] )->implode_str( ', ' );
// Stringable: 'a, b, c'

```

### intersect[​](#intersect "Direct link to intersect")

Intersect the collection with the given items.

```php
... = collect( [ 1, 2, 3 ] )->intersect( [ 2, 3, 4 ] );

```

### intersect\_assoc[​](#intersect_assoc "Direct link to intersect_assoc")

Intersect the collection with the given items, key and value-wise.

```php
$intersect = collect( [ 'name' => 'John' ] )->intersect_assoc( [ 'name' => 'Jane' ] );

```

### intersect\_by\_keys[​](#intersect_by_keys "Direct link to intersect_by_keys")

Intersect the collection with the given items by key.

```php
$intersect = collect( [ 'name' => 'John' ] )->intersect_by_keys( [ 'name' => 'Jane' ] );

```

### is\_empty[​](#is_empty "Direct link to is_empty")

Determine if the collection is empty.

```php
$isEmpty = collect( [] )->is_empty();

```

### is\_not\_empty[​](#is_not_empty "Direct link to is_not_empty")

Determine if the collection is not empty.

```php
$isNotEmpty = collect( [ 1, 2, 3 ] )->is_not_empty();

```

### join[​](#join "Direct link to join")

Join the items in the collection.

```php
$joined = collect( [ 'name', 'age' ] )->join( ', ' );

```

### key\_by[​](#key_by "Direct link to key_by")

Key an associative array by a field or using a callback.

```php
$collection = collect( [
    [ 'name' => 'John', 'age' => 30 ],
    [ 'name' => 'Jane', 'age' => 25 ],
] )->key_by( 'name' );

```

### keys[​](#keys "Direct link to keys")

Get the keys of the collection items.

```php
$keys = collect( [ 'name' => 'John', 'age' => 30 ] )->keys();

```

### last[​](#last "Direct link to last")

Get the last item from the collection.

```php
$item = collect( [ 1, 2, 3 ] )->last();

```

### make[​](#make "Direct link to make")

Create a new collection instance from the given items.

```php
$collection = Collection::make( [1, 2, 3] );

```

### map[​](#map "Direct link to map")

Map the items in the collection to a new callback.

```php
$collection = collect( [ 1, 2, 3 ] )->map( function( $item ) {
    return $item * 2;
} );

```

### map\_into[​](#map_into "Direct link to map_into")

Map the collection into a new class.

```php
$collection = collect( [ 'John', 'Jane' ] )->map_into( User::class );

```

### map\_spread[​](#map_spread "Direct link to map_spread")

Iterates over the collection's items, passing each nested item value into the given callback:

```php
$collection = collect( [ [ 'John', 30 ], [ 'Jane', 25 ] ] )->map_spread( function( $name, $age ) {
    return $name . ' is ' . $age . ' years old';
} );

```

### map\_to\_dictionary[​](#map_to_dictionary "Direct link to map_to_dictionary")

Map the collection to a dictionary.

```php
$dictionary = collect( [
    [
        'name' => 'John',
        'department' => 'Sales',
    ],
    [
        'name' => 'Jane',
        'department' => 'Marketing',
    ],
    [
        'name' => 'Jack',
        'department' => 'Sales',
    ],
] )->map_to_dictionary( function ( $item ) {
    return [
        $item['department'] => $item['name'],
    ];
} ); // [ 'Marketing' => ['John', 'Jane'], 'Sales' => ['Jack']]

```

You can also return false/null to skip an item.

```php
$dictionary = collect( [
    [
        'name' => 'John',
        'department' => 'Sales',
    ],
    [
        'name' => 'Jane',
        'department' => 'Marketing',
    ],
    [
        'name' => 'Jack',
        'department' => 'Sales',
    ],
    [
        'name' => 'Adam',
        'department' => 'Tech',
    ],
    ]
] )->map_to_dictionary( function ( $item ) {
    if ( $item['department'] === 'Sales' ) {
        return false;
    }

    return [
        $item['department'] => $item['name'],
    ];
} ); // ['Marketing' => ['Jane'], 'Tech' => ['Adam']]

```

### map\_to\_groups[​](#map_to_groups "Direct link to map_to_groups")

Alias to `map_to_dictionary`.

### map\_with\_keys[​](#map_with_keys "Direct link to map_with_keys")

Map the collection with the given key / value pairs.

```php
$collection = collect( [
    [
        'name' => 'John',
        'department' => 'Sales',
        'email' => 'john@example.com',
    ],
    [
        'name' => 'Jane',
        'department' => 'Marketing',
        'email' => 'jane@example.com',
    ]
] );

$collection = $collection->map_with_keys( function( $item ) {
    return [ $item['name'] => $item['email'] ];
} );

```

### max[​](#max "Direct link to max")

Get the max value of a given key.

```php
$max = collect( [ 1, 2, 3 ] )->max();

```

### median[​](#median "Direct link to median")

Get the median value of a given key.

```php
$median = collect( [ 1, 2, 3 ] )->median();

```

### merge[​](#merge "Direct link to merge")

Merge the collection with the given items.

```php
$collection = collect( [ 'name' => 'John' ] )->merge( [ 'name' => 'Jane' ] );

```

### merge\_recursive[​](#merge_recursive "Direct link to merge_recursive")

Merge the collection with the given items, recursively.

```php
$collection = collect( [ 'name' => 'John' ] )->merge_recursive( [ 'name' => 'Jane' ] );

```

### min[​](#min "Direct link to min")

Get the min value of a given key.

```php
$min = collect( [ 1, 2, 3 ] )->min();

```

### mode[​](#mode "Direct link to mode")

Get the mode value of a given key.

```php
$mode = collect( [ 1, 2, 2, 3, 3, 3 ] )->mode();

```

### nth[​](#nth "Direct link to nth")

Create a new collection consisting of every n-th element.

```php
$collection = collect( [ 1, 2, 3, 4, 5, 6 ] )->nth( 2 );
// [2, 4, 6]

```

### only[​](#only "Direct link to only")

Create a new collection consisting of the given keys.

```php
$collection = collect( [
    'name' => 'John',
    'department' => 'Sales',
] )->only( [ 'name' ] );

```

### only\_children[​](#only_children "Direct link to only_children")

Create a new collection consisting of only keys that are children of the given keys.

```php
$collection = collect( [
    [
        'name' => 'John',
        'department' => 'Sales',
        'email' => 'john@example.com',
    ],
    [
        'name' => 'Jane',
        'department' => 'Marketing',
        'email' => 'jane@example.com',
    ]
] );

$collection = $collection->only_children( [ 'email', 'name' ] );
// [['name' => 'John', 'email' => 'john@example.com'], ['name' => 'Jane', 'email' => 'jane@example.com']]

```

### pad[​](#pad "Direct link to pad")

Pad the collection to the specified size with a value.

```php
$collection = collect( [ 1, 2, 3 ] )->pad( 5, 0 );
// [1, 2, 3, 0, 0]

```

### partition[​](#partition "Direct link to partition")

Partition the collection into two arrays using the given callback or key.

```php
$collection = collect( [ 1, 2, 3, 4, 5 ] )->partition( function( $value, $key ) {
    return $value > 2;
} );

```

### pipe[​](#pipe "Direct link to pipe")

Pass the collection to the given callback and return the result.

```php
$sum = collect( [1, 2, 3] )->pipe( fn( $collection ) => $collection->sum() );
// 6

```

### pipe\_into[​](#pipe_into "Direct link to pipe_into")

Pass the collection into a new class instance.

```php
class Stats {
    public function __construct( $collection ) {
        $this->total = $collection->sum();
    }
}
$stats = collect( [1, 2, 3] )->pipe_into( Stats::class );
// $stats->total === 6

```

### pipe\_through[​](#pipe_through "Direct link to pipe_through")

Pass the collection through a series of callbacks and return the result.

```php
$result = collect( [1, 2, 3] )->pipe_through([
    fn( $c ) => $c->map( fn( $i ) => $i * 2 ),
    fn( $c ) => $c->sum(),
]);
// 12

```

### pluck[​](#pluck "Direct link to pluck")

Get an array with the values of a given key.

```php
$plucked = collect( [
    [ 'name' => 'John', 'department' => 'Sales' ],
    [ 'name' => 'Jane', 'department' => 'Marketing' ],
] )->pluck( 'name' );

```

### pop[​](#pop "Direct link to pop")

Remove and return the last item from the collection.

```php
$item = collect( [ 1, 2, 3 ] )->pop(); // 3

```

### prepend[​](#prepend "Direct link to prepend")

Prepend an item to the beginning of the collection.

```php
$collection = collect( [ 1, 2, 3 ] )->prepend( 0 );

```

### prepend\_many[​](#prepend_many "Direct link to prepend_many")

Prepend multiple items to the beginning of the collection.

```php
$collection = collect( [ 1, 2, 3 ] )->prepend_many( [ 0, -1, -2 ] );
// [0, -1, -2, 1, 2, 3]

```

### pull[​](#pull "Direct link to pull")

Removes and returns an item from the collection by key.

```php
$item = collect( [ 'name' => 'John' ] )->pull( 'name' );

```

### push[​](#push "Direct link to push")

Push an item onto the end of the collection.

```php
$collection = collect( [ 1, 2, 3 ] )->push( 4 );

```

### put[​](#put "Direct link to put")

Put an item in the collection by key.

```php
$collection = collect( [ 'name' => 'John' ] )->put( 'age', 30 );

```

### random[​](#random "Direct link to random")

Return a random item from the collection.

```php
$random = collect( [ 1, 2, 3 ] )->random();

```

### reduce[​](#reduce "Direct link to reduce")

Reduce the collection to a single value.

```php
$reduced = collect( [ 1, 2, 3 ] )->reduce( function( $carry, $item ) {
    return $carry + $item;
} );

```

### reduce\_spread[​](#reduce_spread "Direct link to reduce_spread")

Reduce the collection to multiple aggregate values at once.

```php
[$min, $max] = collect( [1, 2, 3] )->reduce_spread( function( $min, $max, $value ) {
    return [
        min( $min, $value ),
        max( $max, $value ),
    ];
}, PHP_INT_MAX, PHP_INT_MIN );
// $min = 1, $max = 3

```

### reject[​](#reject "Direct link to reject")

Filter items in the collection using the given callback.

```php
$collection = collect( [ 1, 2, 3 ] )->reject( function( $item ) {
    return $item > 1;
} );

```

### replace[​](#replace "Direct link to replace")

Replace items in the collection with the given items.

```php
$collection = collect( [ 'name' => 'John' ] )->replace( [ 'name' => 'Jane' ] );

```

### replace\_recursive[​](#replace_recursive "Direct link to replace_recursive")

Replace items in the collection with the given items, recursively.

```php
$collection = collect( [ 'name' => 'John' ] )->replace_recursive( [ 'name' => 'Jane' ] );

```

### reverse[​](#reverse "Direct link to reverse")

Reverse items in the collection.

```php
$collection = collect( [ 1, 2, 3 ] )->reverse();

```

### search[​](#search "Direct link to search")

Search the collection for a given value and return the corresponding key if successful.

```php
$key = collect( [ 'name' => 'John' ] )->search( 'John' );

```

### shift[​](#shift "Direct link to shift")

Remove and return the first item from the collection.

```php
$item = collect( [ 1, 2, 3 ] )->shift(); // 1

```

### shuffle[​](#shuffle "Direct link to shuffle")

Shuffle the items in the collection.

```php
$collection = collect( [ 1, 2, 3 ] )->shuffle();

```

### skip[​](#skip "Direct link to skip")

Skip the first n items.

```php
$collection = collect( [ 1, 2, 3 ] )->skip( 2 );

```

### skip\_until[​](#skip_until "Direct link to skip_until")

Skip items in the collection until the given condition is met.

```php
$collection = collect( [ 1, 2, 3, 4, 5 ] )->skip_until( function( $value ) {
	return $value >= 3;
} );
// [3, 4, 5]

$collection = collect( [ 1, 2, 3, 4, 5 ] )->skip_until( 3 );
// [3, 4, 5]

```

### skip\_while[​](#skip_while "Direct link to skip_while")

Skip items in the collection while the given condition is met.

```php
$collection = collect( [ 1, 2, 3, 4, 5 ] )->skip_while( function( $value ) {
	return $value <= 3;
} );
// [4, 5]

$collection = collect( [ 1, 2, 3, 4, 5 ] )->skip_while( function( $value ) {
	return $value < 3;
} );
// [3, 4, 5]

```

### slice[​](#slice "Direct link to slice")

Slice the collection by the given offset and length.

```php
$collection = collect( [ 1, 2, 3 ] )->slice( 1, 2 ); // [2, 3]

```

### sliding[​](#sliding "Direct link to sliding")

Create a "sliding window" view of the items in the collection.

```php
$windows = collect( [1, 2, 3, 4] )->sliding( 2 );
// [[1, 2], [2, 3], [3, 4]]

```

### sole[​](#sole "Direct link to sole")

Get the first item in the collection, but only if exactly one item exists. Throws an exception otherwise.

```php
use Mantle\Support\Item_Not_Found_Exception;
use Mantle\Support\Multiple_Items_Found_Exception;

try {
    $item = collect( [42] )->sole();
} catch ( Item_Not_Found_Exception | Multiple_Items_Found_Exception $e ) {
    // Handle error
}

```

### some[​](#some "Direct link to some")

Alias for the `contains` method.

### sort[​](#sort "Direct link to sort")

Sort the collection with an optional callback.

```php
$collection = collect( [ 3, 2, 1 ] )->sort();

```

### sort\_by[​](#sort_by "Direct link to sort_by")

Sort the collection by the given callback.

```php
$collection = collect( [ 1, 3, 2 ] )->sort_by( function( $item ) {
    return $item;
} );

```

### sort\_by\_desc[​](#sort_by_desc "Direct link to sort_by_desc")

Sort the collection by the given callback in descending order.

```php
$collection = collect( [ 3, 2, 1 ] )->sort_by_desc( function( $item ) {
    return $item;
} );

```

### sort\_desc[​](#sort_desc "Direct link to sort_desc")

Sort the collection in descending order.

```php
$collection = collect( [ 3, 2, 1 ] )->sort_desc();

```

### sort\_keys[​](#sort_keys "Direct link to sort_keys")

Sort the collection by keys.

```php
$collection = collect( [ 'b' => 2, 'a' => 1 ] )->sort_keys();

```

### sort\_keys\_desc[​](#sort_keys_desc "Direct link to sort_keys_desc")

Sort the collection by keys in descending order.

```php
$collection = collect( [ 'b' => 2, 'a' => 1 ] )->sort_keys_desc();

```

### sort\_keys\_using[​](#sort_keys_using "Direct link to sort_keys_using")

Sort the collection keys using a custom callback.

```php
$collection = collect( [ 'b' => 2, 'a' => 1 ] )->sort_keys_using( function( $a, $b ) {
    return strcmp( $a, $b );
} );
// ['a' => 1, 'b' => 2]

```

### splice[​](#splice "Direct link to splice")

Remove and return a portion of the collection.

```php
$collection = collect( [ 1, 2, 3, 4, 5 ] )->splice( 1, 2 );

```

### split[​](#split "Direct link to split")

Split the collection into the given number of groups.

```php
$collection = collect( [ 1, 2, 3, 4, 5 ] )->split( 2 ); // [[1, 2, 3], [4, 5]]

```

### split\_in[​](#split_in "Direct link to split_in")

Split the collection into the given number of groups, filling the first groups completely.

```php
$groups = collect( [1, 2, 3, 4, 5] )->split_in( 2 );
// [[1, 2, 3], [4, 5]]

```

### sum[​](#sum "Direct link to sum")

Get the sum of the given values.

```php
$sum = collect( [ 1, 2, 3 ] )->sum();

$sum = collect( [
    [ 'name' => 'John', 'age' => 30 ],
    [ 'name' => 'Jane', 'age' => 25 ],
] )->sum( 'age' );

```

### take[​](#take "Direct link to take")

Take the first or last n items.

```php
$collection = collect( [ 1, 2, 3 ] )->take( 2 );

```

### take\_until[​](#take_until "Direct link to take_until")

Take items in the collection until the given condition is met. Stops before the item that matches the condition. You can pass a value or a callback.

```php
$collection = collect( [ 1, 2, 3, 4, 5 ] )->take_until( function( $value ) {
    return $value >= 4;
} );
// [1, 2, 3]

$collection = collect( [ 1, 2, 3, 4, 5 ] )->take_until( 3 );
// [1, 2]

```

### take\_while[​](#take_while "Direct link to take_while")

Take items in the collection while the given condition is met. You can pass a value or a callback.

```php
$collection = collect( [ 1, 2, 3, 4, 5 ] )->take_while( function( $value ) {
    return $value < 4;
} );
// [1, 2, 3]

$collection = collect( [ 1, 1, 2, 3, 2 ] )->take_while( 1 );
// [1, 1]

```

### tap[​](#tap "Direct link to tap")

Pass the collection to the given callback and then return the collection.

```php
$collection = collect( [1, 2, 3] )->tap( function( $c ) {
    // Do something with $c
} );

```

### times[​](#times "Direct link to times")

Create a new collection by invoking the callback a given number of times.

```php
$collection = Collection::times( 3, fn( $i ) => $i * 2 );
// [2, 4, 6]

```

### to\_array[​](#to_array "Direct link to to_array")

Convert the collection to a plain array.

```php
$array = collect( [ 1, 2, 3 ] )->to_array();

```

### to\_base[​](#to_base "Direct link to to_base")

Get a base Mantle collection instance from this collection.

```php
$base = $collection->to_base();

```

### to\_json[​](#to_json "Direct link to to_json")

Convert the collection to its JSON representation.

```php
$json = collect( [ 1, 2, 3 ] )->to_json();

```

### to\_pretty\_json[​](#to_pretty_json "Direct link to to_pretty_json")

Get the collection as pretty-printed JSON.

```php
$json = collect( [1, 2, 3] )->to_pretty_json();

```

### toArray[​](#toarray "Direct link to toArray")

Alias for the `to_array` methods.

### transform[​](#transform "Direct link to transform")

Transform each item in the collection using a callback (modifies the collection in place).

```php
$collection = collect( [1, 2, 3] )->transform( fn( $item ) => $item * 2 );
// [2, 4, 6]

```

### trim[​](#trim "Direct link to trim")

Trim the collection's string values.

```php
$collection = collect( [ ' John ', ' Jane ' ] )->trim();

```

### undot[​](#undot "Direct link to undot")

Expand a flattened "dot" notation array into an expanded array.

```php
$collection = collect( [ 'user.name' => 'John' ] )->undot();
// [ 'user' => [ 'name' => 'John' ] ]

```

### unique[​](#unique "Direct link to unique")

Filter the collection for unique items.

```php
$collection = collect( [ 1, 2, 2, 3, 3, 3 ] )->unique();

```

### unique\_strict[​](#unique_strict "Direct link to unique_strict")

Filter the collection with a strict comparison.

```php
$collection = collect( [ 1, 2, 2, 3, 3, 3 ] )->unique_strict();

```

### unless\_empty[​](#unless_empty "Direct link to unless_empty")

Execute a callback if the collection is not empty.

```php
$collection = collect( [ 1, 2, 3 ] )->unless_empty( function( $collection ) {
    // ...
} );

```

### unless\_not\_empty[​](#unless_not_empty "Direct link to unless_not_empty")

Execute a callback if the collection is empty.

```php
$collection = collect( [] )->unless_not_empty( function( $collection ) {
    // ...
} );

```

### unwrap[​](#unwrap "Direct link to unwrap")

Get the underlying array from a collection or arrayable value.

```php
$array = Collection::unwrap( collect( [1, 2, 3] ) );
// [1, 2, 3]

```

### values[​](#values "Direct link to values")

Get the values of the collection items.

```php
$values = collect( [ 'name' => 'John', 'age' => 30 ] )->values();

```

### when\_empty[​](#when_empty "Direct link to when_empty")

Execute a callback if the collection is empty.

```php
$collection = collect( [] )->when_empty( function( $collection ) {
    // ...
} );

```

### when\_not\_empty[​](#when_not_empty "Direct link to when_not_empty")

Execute a callback if the collection is not empty.

```php
$collection = collect( [ 1, 2, 3 ] )->when_not_empty( function( $collection ) {
    // ...
} );

```

### where[​](#where "Direct link to where")

Filter the collection by determining if a specific key / value pair is true.

```php
$collection = collect( [ 'name' => 'John' ] )->where( 'name', 'John' );
$collection = collect( [ 'name' => 'John' ] )->where( 'name', '!=', 'John' );

```

### where\_between[​](#where_between "Direct link to where_between")

Filter the collection by determining if a specific item is between two values.

```php
$collection = collect( [
    [ 'name' => 'Jack', 'age' => 35 ],
    [ 'name' => 'John', 'age' => 30 ],
    [ 'name' => 'Jane', 'age' => 25 ],
] )->where_between( 'age', [ 25, 30 ] );

```

### where\_in[​](#where_in "Direct link to where_in")

Filter the collection by determining if a specific key / value pair is in the given array.

```php
$collection = collect( [ 'name' => 'John' ] )->where_in( 'name', [ 'John' ] );

```

### where\_in\_strict[​](#where_in_strict "Direct link to where_in_strict")

Filter the collection by determining if a specific key / value pair is in the given array.

```php
$collection = collect( [ 'name' => 'John' ] )->where_in_strict( 'name', [ 'John' ] );

```

### where\_instance\_of[​](#where_instance_of "Direct link to where_instance_of")

Filter the collection by determining if a specific item is an instance of the given class.

```php
$collection = collect( [ new User, new Post ] )->where_instance_of( User::class );

```

### where\_not\_between[​](#where_not_between "Direct link to where_not_between")

Filter the collection by determining if a specific item is not between two values.

```php
$collection = collect( [
    [ 'name' => 'Jack', 'age' => 35 ],
    [ 'name' => 'John', 'age' => 30 ],
    [ 'name' => 'Jane', 'age' => 25 ],
] )->where_not_between( 'age', [ 25, 30 ] );

```

### where\_not\_in[​](#where_not_in "Direct link to where_not_in")

Filter the collection by determining if a specific key / value pair is not in the given array.

```php
$collection = collect( [ 'name' => 'John' ] )->where_not_in( 'name', [ 'Jane' ] );

```

### where\_not\_in\_strict[​](#where_not_in_strict "Direct link to where_not_in_strict")

Filter the collection by determining if a specific key / value pair is not in the given array.

```php
$collection = collect( [ 'name' => 'John' ] )->where_not_in_strict( 'name', [ 'Jane' ] );

```

### where\_not\_null[​](#where_not_null "Direct link to where_not_null")

Filter the collection by determining if a specific key / value pair is not null.

```php
$collection = collect( [ 'name' => 'John' ] )->where_not_null( 'name' );

```

### where\_null[​](#where_null "Direct link to where_null")

Filter the collection by determining if a specific key / value pair is null.

```php
$collection = collect( [ 'name' => null ] )->where_null( 'name' );

```

### where\_strict[​](#where_strict "Direct link to where_strict")

Filter the collection by determining if a specific key / value pair is true.

```php
$collection = collect( [ 'name' => 'John' ] )->where_strict( 'name', 'John' );

```

### wrap[​](#wrap "Direct link to wrap")

Wrap the given value in a collection if it isn't already one.

```php
$collection = Collection::wrap( 5 );
// [5]

```

Pass the collection to the given closure and returns the result of the executed closure.

```php
$collection = collect( [ 1, 2, 3 ] );

$piped = $collection->pipe( function ( Collection $collection ) {
    return $collection->sum();
} );

// 6

```

### zip[​](#zip "Direct link to zip")

The `zip` method merges together the values of the given array with the values of the original collection at their corresponding index: