wp_list_filter() │ WP 3.1.0

Filters an array of objects (or an array of arrays) and retrieves from the array those objects that have the specified parameter.

For example, we have an array of objects and we need to get from this array the object whose field post_title is equal to my title. For this, we pass the original array of objects to the parameter $list, and in $args we specify the selection parameters: [ 'post_title' => 'my title' ]. As a result, the function will return a new array with the object we need.

Important: The keys of the main array are preserved! That is, the keys of the elements in the resulting array will be the same as they were in the main one, not in order (0 1 2). That is, you cannot get the first element as $result_array[0].

Therefore, to get the first element of the array, use the function array_shift() or reset().

Works at an early stage of loading WordPress, even before the constant SHORTINIT.

Differences between: wp_list_filter() and wp_filter_object_list()

wp_list_filter( $list, $args, $operator ) — filters the passed array and returns its elements as they are (completely), for example, if the value was an object, the entire object will be returned.
wp_filter_object_list( $list, $args, $operator, $field ) — works exactly the same. But if you specify the 4th parameter $field, then after filtering the array, the function wp_list_pluck() will be triggered and only the field (key) specified in the 4th parameter will be taken from the values of the filtered array.

Use wp_list_sort() when you need to sort an array of objects (or arrays).

Uses: wp_filter_object_list()

1 time — 0.000001 sec (speed of light) | 50000 times — 0.12 sec (very fast) | PHP 7.4.25, WP 5.9

No Hooks.

Returns

Array. An array that was obtained after selection.

Usage

wp_list_filter( $input_list, $args, $operator );

$list(array) (required)

Array of objects that we will work with.

$args(array)

Parameters by which we need to select objects. Specify in the array key => val. val cannot be an array of multiple values - only one value...
Default: array()

$operator(string)

Indicates how to process the parameters specified in $args. Can be:

OR — will keep objects that have any of the specified parameters.
AND — will keep objects that have all the specified parameters at the same time.
NOT — will keep objects that do not have the specified parameters.

Default: 'AND'

Examples

#1 Check if there is an object with the specified value in the array

We have an array of post objects. We need to check if a post with the title 'some_title' is among the posts:

global $posts;
$title = 'some_title';
$the_post = wp_list_filter( $posts, [ 'post_title' => $title ] );

// if the $posts array has a post with the title 'some_title', then
// array_shift( $the_post ) will return this object.

#2 Demonstration of the function

Suppose we have an array of objects. Each object has a field count and some have a value of 0. We need to get all the objects of the array whose count value is not 0, but not the same.

Object array:

$objects_array = [

	57 => (object) [
		'parent' => 80,
		'count' => 9,
	],

	58 => (object) [
		'parent' => 80,
		'count' => 0,
	],

	59 => (object) [
		'parent' => 80,
		'count' => 4,
	],

];

$filtered_array = wp_list_filter( $objects_array, [ 'count' => true ] );

/*
$filtered_array = Array
(
	[57] => stdClass Object
		(
			[parent] => 80
			[count] => 9
		)

	[59] => stdClass Object
		(
			[parent] => 80
			[count] => 4
		)

)
*/

Let's do the same with an array of arrays:

$arrays_array = [

	57 => [
		'parent' => 80,
		'count' => 9,
	],

	58 => [
		'parent' => 80,
		'count' => 0,
	],

	59 => [
		'parent' => 80,
		'count' => 4,
	],

];

$filtered_array = wp_list_filter( $arrays_array, [ 'count' => true ] );

/*
$filtered_array = Array
(
	[57] => Array
		(
			[parent] => 80
			[count] => 9
		)

	[59] => Array
		(
			[parent] => 80
			[count] => 4
		)

)
*/

#3 Assemble the elements without specifying a key

$arr = [ 'foo', 'bar', 'foo', 'bar' ];
$list = wp_list_filter( $arr, array('bar') );

/*
Array
(
	[1] => bar
	[3] => bar
)
*/

#4 More examples

For more examples, see the function description: wp_filter_object_list()

Changelog

Since 3.1.0	Introduced.
Since 4.7.0	Uses `WP_List_Util` class.
Since 5.9.0	Converted into a wrapper for wp_filter_object_list().

`wp_list_filter() wp list filter` code ^{WP 6.9}

wp-includes/functions.php

function wp_list_filter( $input_list, $args = array(), $operator = 'AND' ) {
	return wp_filter_object_list( $input_list, $args, $operator );
}