wp_list_pluck( array $list, int|string $field, int|string $index_key = null )

Pluck a certain field out of each object in a list.


Description Description

This has the same functionality and prototype of array_column() (PHP 5.5) but also supports objects.


Parameters Parameters

$list

(array) (Required) List of objects or arrays

$field

(int|string) (Required) Field from the object to place instead of the entire object

$index_key

(int|string) (Optional) Field from the object to use as keys for the new array.

Default value: null


Top ↑

Return Return

(array) Array of found values. If $index_key is set, an array of found values with keys corresponding to $index_key. If $index_key is null, array keys from the original $list will be preserved in the results.


Top ↑

Source Source

File: wp-includes/functions.php

function wp_list_pluck( $list, $field, $index_key = null ) {
	$util = new WP_List_Util( $list );
	return $util->pluck( $field, $index_key );
}

Top ↑

Changelog Changelog

Changelog
Version Description
4.7.0 Uses WP_List_Util class.
4.0.0 $index_key parameter added.
3.1.0 Introduced.


Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    Contributed by Barbara Ford

    This is an example of how to use this function.

    The following is an array listing foods:

    $foods = array(
    	array(
    		'name'  => 'Banana',
    		'color' => 'Yellow',
    	),
    	array(
    		'name'  => 'Apple',
    		'color' => 'Red',
    	),
    	array(
    		'name'  => 'Lettuce',
    		'color' => 'Green',
    	),
    	array(
    		'name'  => 'Apple',
    		'color' => 'Red',
    	),
    );
    

    The names of each food can easily be “plucked” from the $foods array using wp_list_pluck().

    $food_names = wp_list_pluck( $foods, 'name' ); 

    $food_names will now contain a numerically indexed array of food names equivalent to:

    array(
    	'Banana',
    	'Apple',
    	'Lettuce',
    	'Apple'
    );
  2. Skip to note 2 content
    Contributed by bcworkz

    Use of the $index_key argument is best reserved for unique or index fields, otherwise data could be missing from the returned array. Consider this modified $foods list from the previous example:

    $foods = array(
        array(
            'name'  => 'Banana',
            'color' => 'Yellow',
        ),
        array(
            'name'  => 'Apple',
            'color' => 'Red',
        ),
        array(
            'name'  => 'Kiwi',
            'color' => null,
        ),
        array(
            'name'  => 'Lettuce',
            'color' => 'Green',
        ),
        array(
            'name'  => 'Cherry',
            'color' => 'Red',
        ),
    );

    Using ‘color’ as $index_key is questionable.

    $food_names = wp_list_pluck( $foods, 'name', 'color' );

    $food_names contains an associative array equivalent to:

    array(
        'Yellow' => 'Banana',
        'Red'    => 'Cherry',
         0       => 'Kiwi',
        'Green'  => 'Lettuce',
    )

    The ‘Apple’ value was overwritten by the subsequent ‘Cherry’ since they both had a ‘Red’ index key value. Since ‘Kiwi’ had an unusable color value, its key is simply indexed.

You must log in before being able to contribute a note or feedback.