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