wp_list_filter( array $input_list, array $args = array(), string $operator = 'AND' ): array

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


Description

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.


Top ↑

Parameters

$input_list array Required
An array of objects to filter.
$args array Optional
An array of key => value arguments to match against each object.

Default: array()

$operator string Optional
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'.

Default: 'AND'


Top ↑

Return

array Array of found values.


Top ↑

Source

File: wp-includes/functions.php. View all references

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


Top ↑

Changelog

Changelog
Version Description
5.9.0 Converted into a wrapper for wp_filter_object_list().
4.7.0 Uses WP_List_Util class.
3.1.0 Introduced.

Top ↑

User Contributed Notes

  1. Skip to note 1 content
    Contributed by Felipe Elia

    Example of usage:

    $animals = [
    	[ 'name' => 'alligator', 'fly' => false, 'class' => 'reptile' ],
    	[ 'name' => 'dog',       'fly' => false, 'class' => 'mammal' ],
    	[ 'name' => 'cat',       'fly' => false, 'class' => 'mammal' ],
    	[ 'name' => 'falcon',    'fly' => true,  'class' => 'bird' ],
    	[ 'name' => 'bat',       'fly' => true,  'class' => 'mammal' ],
    ];
    
    wp_list_filter( $animals, [ 'class' => 'mammal' ] );
    // [
    //   [ 'name' => 'dog', ... ]
    //   [ 'name' => 'cat', ... ]
    //   [ 'name' => 'bat', ... ]
    // ]
    
    wp_list_filter( $animals, [ 'class' => 'mammal', 'fly' => true ] );
    // [
    //   [ 'name' => 'bat', ... ]
    // ]
    
    wp_list_filter( $animals, [ 'class' => 'mammal', 'fly' => true ], 'OR' );
    // [
    //   [ 'name' => 'dog', ... ]
    //   [ 'name' => 'cat', ... ]
    //   [ 'name' => 'falcon', ... ]
    //   [ 'name' => 'bat', ... ]
    // ]

You must log in before being able to contribute a note or feedback.