The wp_filter_object_list() WordPress function allows you to easily filter an array of objects based on the provided attributes. In other words, you can provide your matching criteria and get a subset of the data.
Function Overview
wp_filter_object_list( array $list, array $args = array(), string $operator = 'and', bool|string $field = false )
$list
(array) (Required) — An array of objects to filter
$args
(array) (Optional) An array of key => value arguments to match against each object.
Default value: array()
$operator
(string) (Optional) The logical operation to perform: ‘or’ means only one element from the array needs to match, ‘and’ means all elements must match, and ‘not’ means no elements should match.
Default value: ‘and’
$field
(bool|string) (Optional) A field from the object to place instead of the entire object.
Default value: false
Sample Usage
Let’s start with an array of objects:
$list = array(
(object) array( 'name' => 'John', 'gender' => 'male', 'job' => 'Farmer' ),
(object) array( 'name' => 'Paul', 'gender' => 'male', 'job' => 'Blacksmith' ),
(object) array( 'name' => 'Adam', 'gender' => 'male', 'job' => '' ),
(object) array( 'name' => 'Mike', 'gender' => 'male', 'job' => '' ),
(object) array( 'name' => 'Jane', 'gender' => 'female', 'job' => 'Baker' ),
(object) array( 'name' => 'Jill', 'gender' => 'female', 'job' => 'Farmer' ),
);
First, let’s get all the objects from our list that represent unemployed people:
$unemployed = wp_filter_object_list( $list, array('job' => '') );
The result will be a list of all objects where the ‘job’ field is empty:
array
2 =>
object(stdClass)
public 'name' => string 'Adam'
public 'gender' => string 'male'
public 'job' => string ''
3 =>
object(stdClass)
public 'name' => string 'Mike'
public 'gender' => string 'male'
public 'job' => string ''
If you want to get a list of all the farmers, just update the value for the ‘job’ field:
$farmers = wp_filter_object_list( $list, array( 'job' => 'Farmer' ) );
You can also filter the results on multiple attributes:
$female_farmers = wp_filter_object_list( $list, array( 'job' => 'Farmer', 'gender' => 'female' ) );
This will return a list of people who are both females and farmers, which in this case would just be Jill.
The ‘and’ operator is the default. However, you can also use the ‘or’ operator to return a wider dataset:
$females_or_farmers = wp_filter_object_list( $list, array( 'job' => 'Farmer', 'gender' => 'female' ), 'or' );
This will return a list of people who are females or farmers, which in this case would be John, Jane and Jill.
If you want to filter the results and return an array that only has a specific field (e.g. ‘name’), just provide the field name as the fourth argument:
$has_job = wp_filter_object_list( $list, array( 'job' => '' ), 'not', 'name' );
The result would be:
array( 'John', 'Paul', 'Jane', 'Jill' );