Laravel 5: Retrieving Nested Array Values With pluck

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.

#Signature

The signature of the pluck method is:

1public static function pluck(
2    $array,
3    $value,
4    $key = null
5);

#Example Use

Let's use the following class to describe a person:

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

We can create an array of people like so:

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

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:

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

The value of $lastNames would then look like this:

1array {
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$justArrays = [
2    ['firstName' => 'Jane', 'lastName' => 'Carter'],
3    ['firstName' => 'John', 'lastName' => 'Doe'],
4    ['firstName' => 'Jack', 'lastName' => 'Smith']
5];

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

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

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

1array {
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$people = [
2    new Person('Jane', 'Carter'),
3    new Person('John', 'Doe'),
4    new Person('Jack', 'Smith')
5];

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

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

The value of $peopleList would now look like this:

1array {
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:

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

The value of $peopleList would now look like this:

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

#Working With Nested Arrays or 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:

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

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

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

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

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

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

 1array {
 2    object(Person) {
 3        ["firstName"] "Jane"
 4        ["lastName"]  "Carter"
 5        ["job"] {
 6            ["name"] "Senior Developer"
 7        }
 8    }
 9    object(Person) {
10        ["firstName"] "John"
11        ["lastName"]  "Doe"
12        ["job"] object(Job) {
13            ["name"]  "Junior Developer"
14        }
15    }
16    object(Person) {
17        ["firstName"] "Jack"
18        ["lastName"]  "Smith"
19        ["job"] object(Job) {
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:

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

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

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

The same techniques will also work on nested arrays.

#Global array_pluck Helper Function

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

∎