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