wp_filter_object_list() │ WP 3.0.0

Filters the given array of objects by the specified key=>value parameters.

Gets an array with only those objects that match the specified criteria.

Differences between: wp_list_filter() and wp_filter_object_list()

  • wp_list_filter( $list, $args, $operator ) — filters the given array and returns its elements as is (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 specified field (key) in the 4th parameter will be taken from the values of the filtered array.
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.

Returns

Array. array of objects or array of fields. If data could not be retrieved, then an empty array: array().

Usage

wp_filter_object_list( $input_list, $args, $operator, $field );
$list(array) (required)
Array of objects that we will work with.
$args(array)
Parameters by which to select objects. Specify in the array key => val.
Default: array()
$operator(string)

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

  • AND - objects that have all specified in $args parameters.
  • OR - objects that have any of the specified in $args parameters.
  • NOT - objects that do not have the specified in $args parameters.

Default: AND

$field(string)
Field of the object that needs to be retrieved, instead of the entire object.
Default: false

Examples

1

#1 Demo 

$objects = [
	(object) [ 'ID' => 1, 'title' => 'Post One',   'status' => 'publish' ],
	(object) [ 'ID' => 2, 'title' => 'Post Two',   'status' => 'draft' ],
	(object) [ 'ID' => 3, 'title' => 'Post Three', 'status' => 'publish' ],
];

$filtered = wp_filter_object_list( $objects, [ 'status' => 'publish' ] );

/*
$filtered = Array (
	[0] => stdClass Object (
		[ID]     => 1
		[title]  => Post One
		[status] => publish
	)
	[2] => stdClass Object (
		[ID]     => 3
		[title]  => Post Three
		[status] => publish
	)
)
*/

For example, if you specify the 4th parameter to get an array of the specified fields of the objects:

$objects = [
	(object) [ 'ID' => 1, 'title' => 'Post One',   'status' => 'publish' ],
	(object) [ 'ID' => 2, 'title' => 'Post Two',   'status' => 'draft' ],
	(object) [ 'ID' => 3, 'title' => 'Post Three', 'status' => 'publish' ],
];

$filter_args = [ 'status' => 'draft', 'title' => 'Post Three' ];
$filtered = wp_filter_object_list( $objects, $filter_args, 'OR', 'ID' );

/*
$filtered = Array (
	[1] => 2
	[2] => 3
)
*/
0

#2 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.9

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