wp_list_pluck()
Collects a specified field from nested arrays of a multidimensional array.
The function takes an array whose elements are arrays or objects. The second parameter specifies the field of the nested arrays/objects that needs to be collected from each array/object. The function gathers all fields from the list of arrays/objects and returns an array with the collected fields.
See also a similar function: wp_list_filter() - Filters an array of objects and retrieves from the array those objects that match the specified parameters (key=>value).
In PHP, there is a function array_column() that does the same as wp_list_pluck(), only it does not retain the keys of the original array and returns an indexed array:
array_column( $list, $field, $index_key )
Works at an early stage of loading WordPress, even before the constant SHORTINIT.
No Hooks.
Returns
Array. An array with the collected fields. If data could not be retrieved, then an empty array array().
Usage
wp_list_pluck( $list, $field, $index_key );
- $list(array) (required)
- Array of objects or arrays.
- $field(string) (required)
- Name of the field of the nested object or array that needs to be extracted and added to the final array.
- $index_key(string)
- Name of the field of the array that should be used as the key for the returned array. Since version 4.0
Default: null
Examples
Video with examples
#1 Example of operation wp_list_pluck()
This example shows how the function collects nested array fields. Suppose we have an array of arrays from which we need to get all the values of the name field:
// Available array $foods = array( 6 => array( 'name' => 'Banana', 'color' => 'Yellow', ), 9 => array( 'name' => 'Kiwi', 'color' => 'Green', ), 1 => array( 'name' => 'Mandarin', 'color' => 'Orange', ), 3 => array( 'name' => 'Apple', 'color' => 'Red', ), ); // Gather all the fields $food_names = wp_list_pluck( $foods, 'name' ); /* $food_names will contain: Array ( [6] => Banana [9] => Kiwi [1] => Mandarin [3] => Apple ) */ // If you specify the third parameter $food_names = wp_list_pluck( $foods, 'name', 'color' ); /* $food_names will contain: Array ( [Yellow] => Banana [Green] => Kiwi [Orange] => Tangerine [Red] => Apple ) */
#2 Working with objects
This example is more relevant to WP and shows how to collect all the post titles retrieved via get_posts() in one array:
// Get the posts $posts = get_posts(); // Collect post_title fields into an array $posts_titles = wp_list_pluck( $posts, 'post_title' ); /* $posts_titles contains a array: Array ( [0] => 10 premium themes for online store on WordPress [1] => Monitoring non-existent pages (plugin "404 Error Logger") [2] => WP-Cumulus: 3D tag cloud on flash (improved Russian version) [3] => 10 ways to change the RSS feed in WordPress [4] => Webmaster Yandex plugin for Wordpress ) */
#3 Specifying a key from a nested array
Suppose we have such an array:
$foods = array( array( 'id' => 4, 'name' => 'Banana', 'color' => 'Yellow', ), array( 'id' => '5', 'name' => 'Apple', 'color' => 'Red', ), array( 'id' => 2, 'name' => 'Lettuce', 'color' => 'Green', ), array( 'id' => '7', 'name' => 'Apple', 'color' => 'Red', ), );
And we need to get all the name fields and in the final array as keys we need to use the id field:
$food_names = wp_list_pluck( $foods, 'name', 'id' ); /* we get: array( 4 => 'Banana', 5 => 'Apple', 2 => 'Lettuce', 7 => 'Apple' ); */
Changelog
| Since 3.1.0 | Introduced. |
| Since 4.0.0 | $index_key parameter added. |
| Since 4.7.0 | Uses WP_List_Util class. |
wp_list_pluck() wp list pluck code WP 7.0
function wp_list_pluck( $input_list, $field, $index_key = null ) {
if ( ! is_array( $input_list ) ) {
return array();
}
$util = new WP_List_Util( $input_list );
return $util->pluck( $field, $index_key );
}