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.

Contents

Description

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

Top ↑

Parameters

$input_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: null

Top ↑

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.

Top ↑

Source

File: wp-includes/functions.php. View all references 

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

View on Trac View on GitHub

Top ↑

Top ↑

Used By

Used By
Used By Description
update_post_parent_caches() wp-includes/post.php

Updates parent post caches for a list of post objects.
update_post_author_caches() wp-includes/post.php

Updates post author user caches for a list of post objects.
WP_REST_Menu_Items_Controller::prepare_item_for_response() wp-includes/rest-api/endpoints/class-wp-rest-menu-items-controller.php

Prepares a single post output for response.
get_block_templates() wp-includes/block-template-utils.php

Retrieves a list of unified template objects based on a query.
WP_REST_Term_Search_Handler::search_items() wp-includes/rest-api/search/class-wp-rest-term-search-handler.php

Searches the object type content for a given search request.
get_media_states() wp-admin/includes/template.php

Retrieves an array of media states from an attachment.
get_feed_build_date() wp-includes/feed.php

Gets the UTC time of the most recently modified post from WP_Query.
wp_filter_oembed_iframe_title_attribute() wp-includes/embed.php

Filters the given oEmbed HTML to make sure iframes have a title attribute.
WP_REST_Post_Search_Handler::search_items() wp-includes/rest-api/search/class-wp-rest-post-search-handler.php

Searches the object type content for a given search request.
WP_Widget_Media_Gallery::render_media() wp-includes/widgets/class-wp-widget-media-gallery.php

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

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

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

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

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

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

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

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

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

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

Retrieves the query results.
WP_Comment_Query::fill_descendants() wp-includes/class-wp-comment-query.php

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

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

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

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

Adds hidden fields with the data for use in the inline editor for posts and pages.
WP_Media_List_Table::display_rows() wp-admin/includes/class-wp-media-list-table.php
WP_Comments_List_Table::prepare_items() wp-admin/includes/class-wp-comments-list-table.php
get_the_terms() wp-includes/category-template.php

Retrieves the terms of the taxonomy that are attached to the post.
WP_Query::get_posts() wp-includes/class-wp-query.php

Retrieves an array of posts based on query variables.
_default_wp_die_handler() wp-includes/functions.php

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

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

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

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

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

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

Retrieves galleries from the passed post’s content.
get_post_galleries_images() wp-includes/media.php

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

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

Getter.
wp_update_post() wp-includes/post.php

Updates a post with new post data.
Show 36 more used by Hide more used by

Top ↑

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

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

    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.