wp_filter_object_list

The timeline below displays how wordpress function wp_filter_object_list has changed across different WordPress versions. If a version is not listed, refer to the next available version below.

WordPress Version: 6.2

/**
 * 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.
 *
 * @since 3.0.0
 * @since 4.7.0 Uses `WP_List_Util` class.
 *
 * @param array       $input_list An array of objects to filter.
 * @param array       $args       Optional. An array of key => value arguments to match
 *                                against each object. Default empty array.
 * @param string      $operator   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'.
 * @param bool|string $field      Optional. A field from the object to place instead
 *                                of the entire object. Default false.
 * @return array A list of objects or object fields.
 */
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();
}

WordPress Version: 5.8

/**
 * 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.
 *
 * @since 3.0.0
 * @since 4.7.0 Uses `WP_List_Util` class.
 *
 * @param array       $list     An array of objects to filter.
 * @param array       $args     Optional. An array of key => value arguments to match
 *                              against each object. Default empty array.
 * @param string      $operator 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'.
 * @param bool|string $field    Optional. A field from the object to place instead
 *                              of the entire object. Default false.
 * @return array A list of objects or object fields.
 */
function wp_filter_object_list($list, $args = array(), $operator = 'and', $field = false)
{
    if (!is_array($list)) {
        return array();
    }
    $util = new WP_List_Util($list);
    $util->filter($args, $operator);
    if ($field) {
        $util->pluck($field);
    }
    return $util->get_output();
}

WordPress Version: 5.1

/**
 * Filters a list of objects, based on a set of key => value arguments.
 *
 * @since 3.0.0
 * @since 4.7.0 Uses `WP_List_Util` class.
 *
 * @param array       $list     An array of objects to filter
 * @param array       $args     Optional. An array of key => value arguments to match
 *                              against each object. Default empty array.
 * @param string      $operator Optional. The logical operation to perform. 'or' means
 *                              only one element from the array needs to match; 'and'
 *                              means all elements must match; 'not' means no elements may
 *                              match. Default 'and'.
 * @param bool|string $field    A field from the object to place instead of the entire object.
 *                              Default false.
 * @return array A list of objects or object fields.
 */
function wp_filter_object_list($list, $args = array(), $operator = 'and', $field = false)
{
    if (!is_array($list)) {
        return array();
    }
    $util = new WP_List_Util($list);
    $util->filter($args, $operator);
    if ($field) {
        $util->pluck($field);
    }
    return $util->get_output();
}

WordPress Version: 4.7

/**
 * Filters a list of objects, based on a set of key => value arguments.
 *
 * @since 3.0.0
 * @since 4.7.0 Uses WP_List_Util class.
 *
 * @param array       $list     An array of objects to filter
 * @param array       $args     Optional. An array of key => value arguments to match
 *                              against each object. Default empty array.
 * @param string      $operator Optional. The logical operation to perform. 'or' means
 *                              only one element from the array needs to match; 'and'
 *                              means all elements must match; 'not' means no elements may
 *                              match. Default 'and'.
 * @param bool|string $field    A field from the object to place instead of the entire object.
 *                              Default false.
 * @return array A list of objects or object fields.
 */
function wp_filter_object_list($list, $args = array(), $operator = 'and', $field = false)
{
    if (!is_array($list)) {
        return array();
    }
    $util = new WP_List_Util($list);
    $util->filter($args, $operator);
    if ($field) {
        $util->pluck($field);
    }
    return $util->get_output();
}

WordPress Version: 4.5

/**
 * Filters a list of objects, based on a set of key => value arguments.
 *
 * @since 3.0.0
 *
 * @param array       $list     An array of objects to filter
 * @param array       $args     Optional. An array of key => value arguments to match
 *                              against each object. Default empty array.
 * @param string      $operator Optional. The logical operation to perform. 'or' means
 *                              only one element from the array needs to match; 'and'
 *                              means all elements must match; 'not' means no elements may
 *                              match. Default 'and'.
 * @param bool|string $field    A field from the object to place instead of the entire object.
 *                              Default false.
 * @return array A list of objects or object fields.
 */
function wp_filter_object_list($list, $args = array(), $operator = 'and', $field = false)
{
    if (!is_array($list)) {
        return array();
    }
    $list = wp_list_filter($list, $args, $operator);
    if ($field) {
        $list = wp_list_pluck($list, $field);
    }
    return $list;
}

WordPress Version: 4.0

/**
 * Filters a list of objects, based on a set of key => value arguments.
 *
 * @since 3.0.0
 *
 * @param array       $list     An array of objects to filter
 * @param array       $args     Optional. An array of key => value arguments to match
 *                              against each object. Default empty array.
 * @param string      $operator Optional. The logical operation to perform. 'or' means
 *                              only one element from the array needs to match; 'and'
 *                              means all elements must match. Default 'and'.
 * @param bool|string $field    A field from the object to place instead of the entire object.
 *                              Default false.
 * @return array A list of objects or object fields.
 */
function wp_filter_object_list($list, $args = array(), $operator = 'and', $field = false)
{
    if (!is_array($list)) {
        return array();
    }
    $list = wp_list_filter($list, $args, $operator);
    if ($field) {
        $list = wp_list_pluck($list, $field);
    }
    return $list;
}

WordPress Version: 3.7

/**
 * Filters a list of objects, based on a set of key => value arguments.
 *
 * @since 3.0.0
 *
 * @param array $list An array of objects to filter
 * @param array $args An array of key => value arguments to match against each object
 * @param string $operator The logical operation to perform. 'or' means only one element
 *	from the array needs to match; 'and' means all elements must match. The default is 'and'.
 * @param bool|string $field A field from the object to place instead of the entire object
 * @return array A list of objects or object fields
 */
function wp_filter_object_list($list, $args = array(), $operator = 'and', $field = false)
{
    if (!is_array($list)) {
        return array();
    }
    $list = wp_list_filter($list, $args, $operator);
    if ($field) {
        $list = wp_list_pluck($list, $field);
    }
    return $list;
}