Digging into WP Core: wp_list_pluck

Once in a while you find a convenience function that you never really knew before. It’s a method that seems to save a few lines of code or gets rid of some monotonous boilerplate code that you use over and over. Well, wp_list_pluck is one of those functions. But what does it do? how does it work? Why should you use it? Let’s tackle those questions one by one.

What does wp_list_pluck do?

It’s not my intention too rewrite the documentation so I’ll start by pointing you to the codex. It answers most of the technical answers but I’ll be giving some more specific examples and digging deeper into the code. 

Toro sushi
I only want this… nothing else… just this.
Essentially wp_list_pluck plucks a items from a list of lists (a nested/multidimensional array) and makes a new list from that. In WordPress it’s very common to return multidimensional arrays. Getting a list of Posts, for example. In most cases you don’t require every single property in every single post. When you are looping through posts to show excerpts on an archive page, you probably don’t need the main content, as you’ll be displaying the excerpt. It’s like going to a sushi restaurant in Japan with rivers of sushi platters floating by on a conveyor belt and picking only the one piece of fatty tuna belly from each platter that has one and putting it on your place.

In some cases you might want to take just one field, like the ID or the post_title. Perhaps you want to take the titles and see if any titles contain a certain word or you want to pass the IDs to another function. A common scenario might involve getting all the unique author IDs for a group of posts displayed on a page. You can then show all the author bios for posts within a specific list. The straight PHP way would be to use a foreach loop and put the author_id into a list:

$author_ids = array();
foreach($posts as $p){
  $author_ids[] = $p->post_author;
// remove duplicate values;
$author_ids = array_unique( $author_ids );

// loop through $author_ids array and list names
foreach ($author_ids as $id) {
  the_author_meta('display_name', $id);
  echo '<br>';
// You could do anything here, of course.

Using wp_list_pluck() can drastically reduce the code you need to use and still remain readable: 

$author_ids = array_unique( wp_list_pluck( $posts, 'post_author' ) );

// and then loop through that array as before to display what you want.

You may be asking why you’d want to add an additional dependency on a function for what amounts to just a little syntactic sugar. While it’s true that sometimes you can make your code harder to read and more fragile by adding dependency on a function you didn’t create, in this case a foreach loop is essentially just boilerplate. Using wp_list_pluck adheres to the DRY principle ( Don’t Repeat Yourself ) and since this pattern is used over and over when you need to extract on field from an array of objects or arrays, it’s a worthwhile function to use. But, this brings up the question… what does the function actually do?

Going to the source of the matter.

When you start using a new function, it’s a good idea to quickly look at the source code to see if you can figure out what’s going on. If we check out the codex, there’s a link to the source code. At the time of writing, it’s on line 3453, of the file src/wp_includes/functions.php. If you open up that function, you’ll see that it’s a simple function about 10 lines long. 

How wp_list_pluck works

Essentially, wp_list_pluck does what we did, it loops through an array and plucks out one field, returning another array. It has with a little bit of extra code so it can handle arrays of objects, or arrays of arrays. So we can see that `wp_list_pluck` is basically syntactic sugar and shouldn’t add any performance hit. Great! But again, why use it at all. Doesn’t using a function like this make your code more esoteric and hard to understand?

The Attraction of Abstraction. Why use wp_list_pluck

For a simple function like this which is just a wrapper for a foreach loop, it may seem like we’re just making our code more hard to read by using a function, particularly for people new to WordPress, but there are multiple advantages when you abstract your code, even for simple functions like this.

  1. You keep your code DRY ( Don’t Repeat Yourself )
  2. You can enhance readability by reducing lines of code, and lessen the chances of introducing a bug. 
  3. You signal intent. A loop can do many things so it may not be immediately clear what’s going on. A function like this does one thing consistently.
  4. You can benefit from future improvements to the framework. If PHP 7.1 introduces a faster way to iterate through an array, there’s a good chance that WordPress core will implement this code before you will. You will benefit from that improvement from just upgrading WordPress.

To use or not to use… that is the boolean evalutation

Ultimately, when you program you have to make compromises. You have to decide whether maintainability is more important than efficiency. If we wanted the most efficient code possible, we’d write programs in assembly language or straight binary.

Although it’s tempting to just copy and paste a piece of code and use it in your site, I find that taking a few minutes to answer the questions: What does it do and How does it work helps me determine if I should I use it liberally, or with caution. In the case of wp_list_pluck, I choose the former. It’s a simple enough function and when it’s useful, adds clarity to your code. Just the other day, I found it useful to use in confuction with wp_get_object_terms. Perhaps in a future post, I’ll write about that function.

Leave a Reply

Your email address will not be published. Required fields are marked *