Laravel Array Helper Function: array_pluck

pluck($array, $value, $key = null)

The pluck helper method is used to retrieve a list of specific values from a given $array. It is most useful when used against arrays of objects, but will also work with arrays just as well. Let's use the following class to describe a person:

 1<?php
 2 
 3class Person {
 4 
 5    public $firstName = '';
 6 
 7    public $lastName  = '';
 8 
 9    public function __construct($firstName, $lastName)
10    {
11        $this->firstName = $firstName;
12        $this->lastName  = $lastName;
13    }
14 
15}

We can create an array of people like so:

1<?php
2 
3$people = [
4    new Person('Jane', 'Carter'),
5    new Person('John', 'Doe'),
6    new Person('Jack', 'Smith')
7];

At this point all we have is a simple Person class definition an array of person objects, called $people. However, it would be really useful if we had an array of everyone's last name. This is a perfect use case for the pluck method:

1<?php
2 
3use Illuminate\Support\Arr;
4 
5$lastNames = Arr::pluck($people, 'lastName');

The value of $lastNames would then look like this:

1array(3) {
2    [0] "Carter"
3    [1] "Doe"
4    [2] "Smith"
5}

The pluck function will also work on array of arrays. Consider an array of the same people, represented instead by arrays:

1<?php
2 
3$justArrays = [
4    ['firstName' => 'Jane', 'lastName' => 'Carter'],
5    ['firstName' => 'John', 'lastName' => 'Doe'],
6    ['firstName' => 'Jack', 'lastName' => 'Smith']
7];

We could again get an array of all the last names, just like before:

1<?php
2 
3use Illuminate\Support\Arr;
4 
5$lastNames = Arr::pluck($justArrays, 'lastName');

And just as before, the value of $lastNames would be:

1array(3) {
2    [0] "Carter"
3    [1] "Doe"
4    [2] "Smith"
5}

#Returning An Array With a Key/Value Pair

We can also instruct the pluck method to return an array that contains both a key and a value. We do this by passing in a third argument to the pluck function: the $key.

Let's reuse the people array:

1<?php
2 
3$people = [
4    new Person('Jane', 'Carter'),
5    new Person('John', 'Doe'),
6    new Person('Jack', 'Smith')
7];

We can get an array with everyone's firstName as the key, and their lastName as the value like so:

1<?php
2 
3use Illuminate\Support\Arr;
4 
5$peopleList = Arr::pluck($people, 'lastName', 'firstName');

The value of $peopleList would now look like this:

1array(3) {
2    ["Jane"] "Carter"
3    ["John"] "Doe"
4    ["Jack"] "Smith"
5}

This can be reversed, so that the lastName becomes the key and the firstName becomes the value:

1<?php
2 
3use Illuminate\Support\Arr;
4 
5$peopleList = Arr::pluck($people, 'firstName', 'lastName');

The value of $peopleList would now look like this:

1array(3) {
2    ["Carter"] "Jane"
3    ["Doe"]    "John"
4    ["Smith"]  "Jack"
5}

#Working With Nested Arrays And Objects

The $key supports dot notation, which implies that we can search for keys at arbitrary depths when constructing the final array. Let's add a new Job class, which will just be a very simple representation of a job:

 1<?php
 2 
 3class Job {
 4 
 5    public $name = '';
 6 
 7    public function __construct($name)
 8    {
 9        $this->name = $name;
10    }
11 
12}

Now we will modify our Person class to accept a Job as one of its parameters:

 1<?php
 2 
 3class Person {
 4 
 5    public $firstName = '';
 6 
 7    public $lastName  = '';
 8 
 9    public $job       = null;
10 
11    public function __construct($firstName, $lastName, Job $job)
12    {
13        $this->firstName = $firstName;
14        $this->lastName  = $lastName;
15        $this->job       = $job;
16    }
17 
18}

After all of this work, let's build a new array of people, this time with jobs:

1<?php
2 
3$people = [
4    new Person('Jane', 'Carter', new Job('Senior Developer')),
5    new Person('John', 'Doe', new Job('Junior Developer')),
6    new Person('Jack, 'Smith', new Job('Marketing Manager'))
7];

After all of this work, we now have an array that looks like this:

 1array(3) {
 2    [0] object(Person)#138 (3) {
 3        ["firstName"] "Jane"
 4        ["lastName"] "Carter"
 5        ["job"] object(Job)#139 (1) {
 6            ["name"] "Senior Developer"
 7        }
 8    }
 9    [1] object(Person)#140 (3) {
10        ["firstName"] "John"
11        ["lastName"] "Doe"
12        ["job"] object(Job)#141 (1) {
13            ["name"] "Junior Developer"
14        }
15    }
16    [2] object(Person)#142 (3) {
17        ["firstName"] "Jack"
18        ["lastName"] "Smith"
19        ["job"] object(Job)#143 (1) {
20            ["name"] "Marketing Manager"
21        }
22    }
23}

What we want to do now is return an array where the job name is the key, and the person's first name is the value. Let's call this array $filledPositions:

1<?php
2 
3use Illuminate\Support\Arr;
4 
5$filledPositions = Arr::pluck($people, 'firstName', 'job.name');

Notice that this time the value for $key is expressed in dot notation. This will produce the following results:

1array(3) {
2    ["Senior Developer"]  "Jane"
3    ["Junior Developer"]  "John"
4    ["Marketing Manager"] "Jack"
5}

The same techniques will also work on nested arrays.

#array_pluck($array, $value, $key = null)

The array_pluck function is a shortcut to calling Arr::pluck. This function is declared in the global namespace.

∎