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

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

Contents

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

Expand full source code Collapse full source code View on Trac

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 ↑

Top ↑

Used By Used By

Used By
Used By Description
wp-includes/feed.php: get_feed_build_date()

Get the timestamp of the most recently modified post from WP_Query.
wp-includes/widgets/class-wp-widget-media-gallery.php: WP_Widget_Media_Gallery::render_media()

Render the media on the frontend.
wp-includes/widgets/class-wp-widget-media-audio.php: WP_Widget_Media_Audio::render_media()

Render the media on the frontend.
wp-includes/widgets/class-wp-widget-media-video.php: WP_Widget_Media_Video::render_media()

Render the media on the frontend.
wp-includes/widgets/class-wp-widget-media.php: WP_Widget_Media::form()

Outputs the settings update form.
wp-includes/widgets/class-wp-widget-media.php: WP_Widget_Media::widget()

Displays the widget on the front-end.
wp-includes/widgets/class-wp-widget-media-image.php: WP_Widget_Media_Image::render_media()

Render the media on the frontend.
wp-admin/includes/class-wp-community-events.php: WP_Community_Events::trim_events()

Prepares the event list for presentation.
wp-includes/class-wp-customize-manager.php: WP_Customize_Manager::import_theme_starter_content()

Import theme starter content into the customized state.
wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php: WP_REST_Posts_Controller::prepare_item_for_response()

Prepares a single post output for response.
wp-includes/rest-api/endpoints/class-wp-rest-post-types-controller.php: WP_REST_Post_Types_Controller::prepare_item_for_response()

Prepares a post type object for serialization.
wp-includes/class-wp-term-query.php: WP_Term_Query::get_terms()

Get terms, based on query_vars.
wp-includes/class-wp-comment-query.php: WP_Comment_Query::fill_descendants()

Fetch descendants for located comments.
wp-includes/class-wp-customize-manager.php: WP_Customize_Manager::unsanitized_post_values()

Get dirty pre-sanitized setting values in the current customized state.
wp-admin/includes/class-wp-automatic-updater.php: WP_Automatic_Updater::send_debug_email()

Prepares and sends an email of a full log of background update results, useful for debugging and geekery.
wp-admin/includes/taxonomy.php: get_terms_to_edit()

Get comma-separated list of terms available to edit for the given post ID.
wp-admin/includes/class-wp-plugin-install-list-table.php: WP_Plugin_Install_List_Table::prepare_items()
wp-admin/includes/template.php: _media_states()

Function to echo the attachment media states as HTML.
wp-admin/includes/template.php: get_inline_data()

Adds hidden fields with the data for use in the inline editor for posts and pages.
wp-admin/includes/revision.php: wp_prepare_revisions_for_js()

Prepare revisions for JavaScript.
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()

Retrieve the terms of the taxonomy that are attached to the post.
wp-includes/functions.php: _default_wp_die_handler()

Kills WordPress execution and displays HTML page with an error message.
wp-includes/widgets/class-wp-widget-recent-comments.php: WP_Widget_Recent_Comments::widget()

Outputs the content for the current Recent Comments widget instance.
wp-includes/class-wp-tax-query.php: WP_Tax_Query::transform_query()

Transforms a single query, from one field to another.
wp-includes/taxonomy.php: is_object_in_term()

Determine if the given object is associated with any of the given terms.
wp-includes/taxonomy.php: wp_insert_term()

Add a new term to the database.
wp-includes/taxonomy.php: wp_delete_term()

Removes a term from the database.
wp-includes/media.php: get_post_galleries_images()

Retrieve the image srcs from galleries from a post’s content, if present
wp-includes/media.php: wp_enqueue_media()

Enqueues all scripts, styles, settings, and templates necessary to use all media JS APIs.
wp-includes/class-wp-post.php: WP_Post::__get()

Getter.
Show 27 more used by Hide more used by

Top ↑

User Contributed Notes User Contributed Notes

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

    Expand full source codeCollapse full source code

    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
    You must log in to vote on the helpfulness of this noteVote results for this note: 4You must log in to vote on the helpfulness of this note
    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',
    ),
);

    Expand full source codeCollapse full source code

    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.