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