wp_list_filter() │ WP 3.1.0

Filters a list of objects, based on a set of key => value arguments.

Retrieves the objects from the list that match the given arguments. Key represents property name, and value represents property value.

If an object has more properties than those specified in arguments, that will not disqualify it. When using the 'AND' operator, any missing properties will disqualify it.

If you want to retrieve a particular field from all matching objects, use wp_filter_object_list() instead.

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.

Return

Array. Array of found values.

Usage

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

$list(array) (required): An array of objects to filter.
$args(array): An array of key => value arguments to match against each object.
Default: empty array
$operator(string): The logical operation to perform. 'AND' means all elements from the array must match. 'OR' means only one element needs to match. 'NOT' means no elements may match.
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 ] );
$the_post = array_shift( $the_post );

// if the $posts array has a post with the title 'some_title', then
// array_shift( $the_post ) will return this object.
if( $the_post ){
	echo $the_post->post_title;
}

#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.1.1}

wp-includes/functions.php

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