Isak Berglind

Isak Berglind

Differentiate Laravel collection methods

Isak Berglind • May 31, 2018

php javascript

Laravel collections is one of my favorite features of Laravel. I use them about every time I need to loop through something or deal with arrays. Some methods are quite similar to each other, though, and even though I use collections on a daily basis, I often find myself scanning through the documentation for those methods that I always mix up.

Many of the methods are self explainable, but some have a more cryptic name and are a bit more tricky to get a grip of.

In this article I will group some of the collection methods I’ve had trouble to differentiate, according to their use case. Then i will explain the difference between them. Because it’s summertime and soon friday, I will do it with an afterwork theme.

This article assumes you know at least the basics about how collections work and how to use them. If you never worked with them before, I would recommend you to go and read the documentation, and after you’ve done that — check out Adam Wathans fantastic book on the subject.

Getting items from the collection

Is this section we will start of easy, and explore the differences between all(), get(), pull(), pluck() and take()

all()

Gets all items from the collection

$drinks = collect(["beer" => "heineken", "vodka" => "absolute", "gin" => "beefeater"]);
$drinks->all(); // ["beer" => "heineken", "vodka" => "absolute", "gin" => "beefeater"]

get()

Gets an item by key.

$drinks = collect(["beer" => "heineken", "vodka" => "absolute"]);
$drinks->get("beer"); // "heineken"

pull()

Exactly like get, but it also removes the item from the collection

$drinks = collect(["beer" => "heineken", "vodka" => "absolute"]);
$drinks->pull("beer"); // "heineken"
$drinks->all() // ["vodka" => "absolute"]

pluck()

Like get, but you use it on a collection of arrays, and it gets all values with the given key from all arrays.

$fridge = collect([
    ["beer" => "heineken", "vodka" => "absolute"],
    ["beer" => "carlsberg", "vodka" => "smirnoff", "gin" => "beefeater"],
    ["beer" => "stockholm", "vodka" => "svedka"],
]);
$fridge->pluck("beer"); // ["heineken", "carlsberg", "stockholm"]

take()

Gets a number of items from the start (starts from the end if you supply a negative value).

$drinks = collect(["beer" => "heineken", "vodka" => "absolute", "gin" => "beefeater"]);
$drinks->take(2); // ["beer" => "heineken", "vodka" => "absolute"];

Merging

Sometimes you want to merge stuff together. But as it turns out there are bunch of different ways you can do this. Here we will look at concat(), merge(), union(), combine() and zip()

merge()

Merges two collections together. If any key in the merging collection matches a key in the original collection, it will be overwritten

$drinks = collect(["beer" => "heineken", "vodka" => "absolute", "gin" => "beefeater"]);
$drinks->merge(["beer" => "corona", "rum" => "captain morgan"]); // ["beer" => "corona", "vodka" => "absolute", "gin" => "beefeater", "rum" => "captain morgan"]

union()

Like merge(), but keeps the original key in case of a key collision.

$drinks = collect(["beer" => "heineken", "vodka" => "absolute", "gin" => "beefeater"]);
$merged = $drinks->union(["beer" => "corona", "rum" => "captain morgan"]); // ["beer" => "heineken", "vodka" => "absolute", "gin" => "beefeater", "rum" => "captain morgan"]

concat()

Appends only the VALUES of the collection. Therefore no overwrites.

$beers = collect(["heineken", "guinness", "samuel adams"]);
$beers->concat(["mexican beer" => "corona"]);
// ["heineken", "guinness", "samuel adams", "corona"]

combine()

Makes the combining collections values the keys of the combined collections values

$drinks = collect(["beer", "vodka"]);
$drinks->combine(["heineken", "absolut"]);
// ["beer" => heineken", "vodka" => "absolute"]

zip()

Almost like combine(), but instead of making key value pairs in the same array, zip “zips” the values into their own arrays.

$drinks = collect(["beer", "vodka"]);
$drinks->zip(["heineken", "absolut"]);
// [["beer", "heineken"], ["vodka", "absolute"]]

Looking for specific values

Sometimes you need to find out if something exists in your collection. Of course there are some methods to help you out. Here we will inspect has() and contains().

has()

Checks if a KEY exists

$drinks = collect(["beer" => "heineken", "vodka" => "absolute", "gin" => "beefeater"]);
$drinks->has("beer"); // true

contains()

Checks if a VALUE exists

$drinks = collect(["beer" => "heineken", "vodka" => "absolute", "gin" => "beefeater"]);
$drinks->contains("heineken"); // true

Chunking

Here we will check out breaking a collection into smaller pieces with chunk() and split()

chunk()

Divides the collection into several collections of gives size

$snack = collect(["p","e","a","n","u","t","s"]);
$snack->chunk(2); // [["p","e"],["a","n"],["u","t"],["s"]]

split()

Divides the collection into given number of collections

$snack = collect(["p","e","a","n","u","t","s"]);
$snack->split(2); // [["p","e","a","n"],["u","t","s"]]

Flattening

A multi-dimentional array can sometimes go too deep. If that’s the case — flatten() and collapse() has you covered

flatten()

flattens the collection, removes the keys on the top level. A level can be specified.

$drinks = collect([["beer" => "heineken"], ["vodka" => "absolute"]]);
$drinks->flatten(); // ["heineken", "absolute"]

collapse()

flattens the collection, but keeps the keys

$drinks = collect([["beer" => "heineken"], ["vodka" => "absolute"]]);
$drinks->collapse(); // ["beer" => "heineken", "vodka" => "absolute"]

Adding items

If you want to add more items to the collection, prepend(), push() and put() is at your service

prepend()

Adds an item to the beginning of a collection. you can provide a key as the second parameter

$party = collect(["a","p","p","y","h","o","u","r"]);
$party->prepend("h"); // ["h",a","p","p","y","h","o","u","r"]

push()

Adds an item to the end of a collection. you CAN NOT provide a key as the second parameter, if thats what you want, check out put()

$party = collect(["h","a","p","p","y","h","o","u"]);
$party->push("r"); // ["h",a","p","p","y","h","o","u","r"]

put()

puts a given value at a given key

$drinks = collect(["beer" => "heineken", "vodka" => "absolute"]);
$drinks->put("rum", "captain morgan"); // ["beer" => "heineken", "vodka" => "absolute", "rum" => "camptain morgan"]

Conclusion

I hope I’ve brought some clarit to some methods for you. If so, please give me a shout out on twitter. If you learnt nothing, then shout at me on twitter ;) You find me at @Isak_Berglind