wppaste
WordPress

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

Since
3.1.0, 4.0.0, 4.7.0
Source
wp-includes/functions.php:5383

Extracts one field from every object or array in a list, returning a flat array of just those values. Pass $index_key to re-key the result by a second field instead of keeping the original list's keys. It works on arrays of stdClass objects, such as get_posts() or get_terms() results, as well as associative arrays, which is what sets it apart from PHP's native array_column(). If $input_list is not an array, the function quietly returns an empty array rather than throwing a warning.

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.

Compatibility

WordPress
since 4.7.0
PHP
7.4–8.6-dev
  • 6.7.7
  • 6.8.8
  • 6.9.7
  • 7.0.4
  • 7.1.0

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$input_listarray
List of objects or arrays.
$fieldint|string
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.Default: null

Return value

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.

Code examples

Every example is editable and runs in a real WordPress booted in your browser by WordPress Playground. Press Run, then edit the code: clicking away re-runs it. Nothing is sent anywhere until you do.

Get post titles keyed by post ID

Fetch a batch of posts and reduce them to a simple ID-to-title map for a dropdown or debug dump.

$posts = get_posts( array(
	'post_type'      => 'post',
	'posts_per_page' => 5,
) );

$titles_by_id = wp_list_pluck( $posts, 'post_title', 'ID' );

echo '<pre>' . esc_html( print_r( $titles_by_id, true ) ) . '</pre>';

get_posts() returns WP_Post objects, and wp_list_pluck() reads their properties directly without any get_ prefix.

Build a lookup table of category names by term ID

Pull all categories and turn them into a term_id-to-name array for quick lookups elsewhere in a template.

$categories = get_terms( array(
	'taxonomy'   => 'category',
	'hide_empty' => false,
) );

$names_by_id = wp_list_pluck( $categories, 'name', 'term_id' );

echo '<pre>' . esc_html( print_r( $names_by_id, true ) ) . '</pre>';

get_terms() can return a WP_Error on failure, so check is_wp_error() before passing its result to wp_list_pluck() in real code.

Common problems and fixes · 4

Why does wp_list_pluck() give me back an empty array?

The function checks is_array( $input_list ) first and returns array() immediately if that fails. Passing a WP_Query object, false, or null instead of an actual array of posts or terms triggers this silently, with no warning.

Why did my array keys change after calling wp_list_pluck()?

When $index_key is left at its default of null, wp_list_pluck() preserves the original array's keys in the result. As soon as you pass an $index_key argument, the returned array is re-keyed by that field instead, which is easy to forget when you only meant to grab values.

Can I lose entries when using an $index_key that isn't unique?

Since $index_key becomes the array key of the result, two objects sharing the same value for that field will collide, and the later one silently overwrites the earlier one in the returned array. This is ordinary PHP array behavior, not something wp_list_pluck() guards against.

Does wp_list_pluck() work if some items are objects and others are arrays?

Yes. Unlike PHP's array_column(), which historically required arrays, wp_list_pluck() is built to handle a mixed list of stdClass objects and associative arrays in the same call, per its own description.

Alternatives and related functions

array_column
When every item in the list is already a plain array (not an object) and you're fine with the native PHP function's behavior.
wp_list_filter
When you need to narrow the list down to matching items instead of extracting one field from every item.
wp_list_sort
When you need the objects or arrays themselves, sorted by a field, rather than a flat list of that field's values.
WP_List_Util
When you need to pluck and filter or sort the same list in one pass, since wp_list_pluck() itself is just a thin wrapper around this class.

Performance profile

How much work a call to wp_list_pluck() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class
Trivial

Touches nothing outside its own arguments.

Scaling
Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions
6–14

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 15.

Plugin surface
None

Nothing here hands control to plugin code.

Called by
44

44 places in core call this, so the cost is paid more often than your own code shows.

What one call costs · 2 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost wp_list_pluck() can have, taken from its control-flow graph on PHP 8.5.

WhenInstructionsCalls it makes
!is_array($input_list)6none
is_array($input_list)14->pluck()

Across PHP versions

Compiles the same on PHP 7.4, 8.1, 8.2, 8.3, 8.4, 8.5 and 8.6-dev: 15 instructions, 6–14 executed per call, 1 branch. The work does not change between versions.

An instruction is not a fixed amount of time, so a matching count is not necessarily the same speed; what it rules out is a difference in the work itself.

Uses · 1

Used by · 44

Show all 44

Source code

View on Trac View on GitHub 

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

Introduced in 3.1.0. Unchanged from 6.7.7 through 7.1.0.

  1. 6.7.7
  2. 6.8.8
  3. 6.9.7
  4. 7.0.4
  5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

4.7.0
Uses WP_List_Util class.from the docblock
4.0.0
$index_key parameter added.from the docblock
3.1.0
Introduced.from the docblock

About this page

Parsed data
Generated from the wordpress-develop 6.9.7 tag, from src/wp-includes/functions.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.
Corrections
Something wrong on this page? Report it and it gets fixed in the next regeneration.