wp_filter_object_list() │ WP 3.0.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.

When using the $field argument, this function can also retrieve a particular field from all matching objects, whereas wp_list_filter() only does the filtering.

Uses: WP_List_Util::filter()
Used By: get_post_stati(), get_post_types(), wp_list_filter()
1 time — 0.000001 sec (speed of light) | 50000 times — 0.95 sec (very fast) | PHP 7.1.11, WP 4.9.8

No Hooks.

Return

Array. A list of objects or object fields.

Usage

wp_filter_object_list( $input_list, $args, $operator, $field );
$input_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'
$field(true|false|string)
A field from the object to place instead of the entire object.
Default: false

Examples

0

#1 Selecting objects according to the specified parameters

Suppose we've done a selection of posts and we have an array of post objects $posts. Which contains objects like this:

Array
(
	[0] => WP_Post Object (
			[ID] => 2773
			[post_author] => 1
			[post_date] => 2013-06-12 21:09:57
			[post_date_gmt] => 2013-06-12 21:09:57
			[post_content] => article content
			[post_title] => Huge text for the "content" script example
			[post_excerpt] =>
			[post_status] => publish
			[comment_status] => open
			[ping_status] => open
			[post_password] =>
			[post_name] => post_name_ogromniy_text
			[to_ping] =>
			[pinged] =>
			[post_modified] => 2013-07-30 21:40:25
			[post_modified_gmt] => 2013-07-30 21:40:25
			[post_content_filtered] =>
			[post_parent] => 0
			[guid] => http://example.com/?p=2773
			[menu_order] => 0
			[post_type] => post
			[post_mime_type] =>
			[comment_count] => 0
	)
	[1] => WP_Post Object ( ... )
)

We need to get the IDs of posts with author=1 and comments open (comment_status=open) from this array. Use wp_filter_object_list():

$args = array('post_author'=>'1', 'comment_status'=>'open');

$filtered_posts = wp_filter_object_list( $posts, $args, 'or', 'ID' );

$filtered_posts will contain:

Array
(
	[0] => 19
	[1] => 23
	[2] => 34
	[3] => 45
	[4] => 56
	[5] => 67
	[6] => 78
)

The parameter "or" tells the function to select posts with post_author=1 or comment_status=open. If you specify "and", the posts post_author=1 and comment_status=open will be selected.

'ID' means to return an array with the values of the object's ID field. If you don't specify this parameter, the whole object will be returned, not a specific field.

Changelog

Since 3.0.0 Introduced.
Since 4.7.0 Uses WP_List_Util class.

wp_filter_object_list() code WP 6.5.2

wp-includes/functions.php 
function wp_filter_object_list( $input_list, $args = array(), $operator = 'and', $field = false ) {
	if ( ! is_array( $input_list ) ) {
		return array();
	}

	$util = new WP_List_Util( $input_list );

	$util->filter( $args, $operator );

	if ( $field ) {
		$util->pluck( $field );
	}

	return $util->get_output();
}

array list help functions (sorting arrays objects)

Helper Functions