Question

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

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

---

参数

$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

---

返回值

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

---

源代码

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

---

更新日志

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

---

相关函数

Uses

• wp-includes/class-wp-list-util.php: WP_List_Util::__construct()

---

Used By

• wp-includes/widgets/class-wp-widget-media-audio.php: WP_Widget_Media_Audio::render_media()
• wp-includes/widgets/class-wp-widget-media-video.php: WP_Widget_Media_Video::render_media()
• wp-includes/widgets/class-wp-widget-media.php: WP_Widget_Media::form()
• wp-includes/widgets/class-wp-widget-media.php: WP_Widget_Media::widget()
• wp-includes/widgets/class-wp-widget-media-image.php: WP_Widget_Media_Image::render_media()
• wp-includes/class-wp-customize-manager.php: WP_Customize_Manager::import_theme_starter_content()
• wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php: WP_REST_Posts_Controller::prepare_item_for_response()
• wp-includes/rest-api/endpoints/class-wp-rest-post-types-controller.php: WP_REST_Post_Types_Controller::prepare_item_for_response()
• wp-includes/class-wp-term-query.php: WP_Term_Query::get_terms()
• wp-includes/class-wp-comment-query.php: WP_Comment_Query::fill_descendants()
• wp-includes/class-wp-customize-manager.php: WP_Customize_Manager::unsanitized_post_values()
• wp-admin/includes/class-wp-automatic-updater.php: WP_Automatic_Updater::send_debug_email()
• wp-admin/includes/taxonomy.php: get_terms_to_edit()
• wp-admin/includes/template.php: _media_states()
• wp-admin/includes/template.php: get_inline_data()
• wp-admin/includes/revision.php: wp_prepare_revisions_for_js()
• wp-admin/includes/class-wp-media-list-table.php: WP_Media_List_Table::display_rows()
• wp-admin/includes/class-wp-comments-list-table.php: WP_Comments_List_Table::prepare_items()
• wp-includes/category-template.php: get_the_terms()
• wp-includes/widgets/class-wp-widget-recent-comments.php: WP_Widget_Recent_Comments::widget()
• wp-includes/taxonomy.php: is_object_in_term()
• wp-includes/taxonomy.php: wp_insert_term()
• wp-includes/taxonomy.php: wp_delete_term()
• wp-includes/media.php: get_post_galleries_images()
• wp-includes/media.php: wp_enqueue_media()
• wp-includes/class-wp-post.php: WP_Post::__get()
Show 21 more used by Hide more used by

---

User Contributed Notes

1. Skip to note content You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note 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'
   );

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.