Skip to main content
Version: 1.x

Collections

Mantle includes Laravel's collections package 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​

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.

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.

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.

use function Mantle\Support\Helpers\collect;

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

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

Available Methods​

add​

The add method adds an item to the collection.

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

all​

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

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

average​

Alias for the avg method.

avg​

Get the average value of a given key.

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

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

chunk​

Chunk the collection into smaller collections of a given size.

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

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

collapse​

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

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

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

combine​

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

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

concat​

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

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

contains_one_item​

Determine if the collection contains only one item.

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

contains_strict​

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

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

contains​

Determine if the collection contains a given item.

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

count_by​

Count the occurrences of values in the collection.

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

count​

Get the number of items in the collection.

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

cross_join​

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

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

dd​

Dump the collection and end the script execution.

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

diff_assoc​

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

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

diff_assoc_using​

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

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

diff_keys​

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

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

diff​

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

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

doesnt_contain​

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

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

dump​

Dump the collection.

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

duplicates_strict​

Get the items in the collection that have duplicate values.

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

duplicates​

Get the items in the collection that have duplicate values.

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

each_spread​

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

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

each​

Iterate over the items in the collection.

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

every​

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

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

except​

Get all items except for those with the specified keys.

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

filter​

Filter the items in the collection using the given callback.

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

first_where​

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

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

first​

Get the first item from the collection.

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

flat_map​

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

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

flatten​

Flatten a multi-dimensional collection into a single dimension.

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

flip​

Flip the items in the collection.

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

for_page​

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

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

forget​

Remove an item from the collection by key.

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

get​

Get an item from the collection.

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

group_by​

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

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

has​

Determine if an item exists in the collection by key.

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

implode​

Join the items in the collection.

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

intersect_assoc​

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

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

intersect_by_keys​

Intersect the collection with the given items by key.

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

intersect​

Intersect the collection with the given items.

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

is_empty​

Determine if the collection is empty.

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

is_not_empty​

Determine if the collection is not empty.

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

join​

Join the items in the collection.

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

key_by​

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

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

keys​

Get the keys of the collection items.

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

last​

Get the last item from the collection.

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

map_into​

Map the collection into a new class.

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

map_spread​

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

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

map_to_dictionary​

Map the collection to a dictionary.

$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.

$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​

Alias to map_to_dictionary.

map_with_keys​

Map the collection with the given key / value pairs.

$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'] ];
} );

map​

Map the items in the collection to a new callback.

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

max​

Get the max value of a given key.

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

median​

Get the median value of a given key.

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

merge_recursive​

Merge the collection with the given items, recursively.

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

merge​

Merge the collection with the given items.

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

min​

Get the min value of a given key.

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

mode​

Get the mode value of a given key.

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

nth​

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

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

only_children​

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

$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']]

only​

Create a new collection consisting of the given keys.

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

pad​

Pad the collection to the specified size with a value.

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

partition​

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

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

pipe​

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

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

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

// 6

pluck​

Get an array with the values of a given key.

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

pop​

Remove and return the last item from the collection.

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

prepend​

Prepend an item to the beginning of the collection.

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

pull​

Removes and returns an item from the collection by key.

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

push​

Push an item onto the end of the collection.

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

put​

Put an item in the collection by key.

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

random​

Return a random item from the collection.

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

reduce​

Reduce the collection to a single value.

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

reject​

Filter items in the collection using the given callback.

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

replace_recursive​

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

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

replace​

Replace items in the collection with the given items.

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

reverse​

Reverse items in the collection.

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

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

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

shift​

Remove and return the first item from the collection.

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

shuffle​

Shuffle the items in the collection.

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

skip​

Skip the first n items.

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

slice​

Slice the collection by the given offset and length.

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

some​

Alias for the contains method.

sort_by_desc​

Sort the collection by the given callback in descending order.

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

sort_by​

Sort the collection by the given callback.

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

sort_desc​

Sort the collection in descending order.

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

sort_keys_desc​

Sort the collection by keys in descending order.

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

sort_keys​

Sort the collection by keys.

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

sort​

Sort the collection with an optional callback.

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

splice​

Remove and return a portion of the collection.

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

split​

Split the collection into the given number of groups.

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

sum​

Get the sum of the given values.

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

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

take​

Take the first or last n items.

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

to_array​

Convert the collection to a plain array.

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

to_json​

Convert the collection to its JSON representation.

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

toArray​

Alias for the to_array methods.

trim​

Trim the collection's string values.

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

unique_strict​

Filter the collection with a strict comparison.

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

unique​

Filter the collection for unique items.

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

unless_empty​

Execute a callback if the collection is not empty.

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

unless_not_empty​

Execute a callback if the collection is empty.

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

values​

Get the values of the collection items.

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

when_empty​

Execute a callback if the collection is empty.

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

when_not_empty​

Execute a callback if the collection is not empty.

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

where_between​

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

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

where_in_strict​

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

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

where_in​

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

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

where_instance_of​

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

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

where_not_between​

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

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

where_not_in_strict​

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

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

where_not_in​

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

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

where_not_null​

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

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

where_null​

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

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

where_strict​

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

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

where​

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

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

zip​

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