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

Plucks a certain field out of each object or array in an array.

Description

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

Parameters

$input_listarrayrequired
List of objects or arrays.
$fieldint|stringrequired
Field from the object to place instead of the entire object.
$index_keyint|stringoptional
Field from the object to use as keys for the new array.

Default:null

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 $input_list will be preserved in the results.

Source

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 );
}

Changelog

VersionDescription
4.7.0Uses WP_List_Util class.
4.0.0$index_key parameter added.
3.1.0Introduced.

User Contributed Notes

  1. Skip to note 3 content

    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 4 content

    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.