wp_list_filter

The timeline below displays how wordpress function wp_list_filter 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.
 *
 * If you want to retrieve a particular field from all matching objects,
 * use wp_filter_object_list() instead.
 *
 * @since 3.1.0
 * @since 4.7.0 Uses `WP_List_Util` class.
 * @since 5.9.0 Converted into a wrapper for `wp_filter_object_list()`.
 *
 * @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'.
 * @return array Array of found values.
 */
function wp_list_filter($input_list, $args = array(), $operator = 'AND')
{
    return wp_filter_object_list($input_list, $args, $operator);
}

WordPress Version: 5.9

/**
 * 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.
 *
 * If you want to retrieve a particular field from all matching objects,
 * use wp_filter_object_list() instead.
 *
 * @since 3.1.0
 * @since 4.7.0 Uses `WP_List_Util` class.
 * @since 5.9.0 Converted into a wrapper for `wp_filter_object_list()`.
 *
 * @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'.
 * @return array Array of found values.
 */
function wp_list_filter($list, $args = array(), $operator = 'AND')
{
    return wp_filter_object_list($list, $args, $operator);
}

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.
 *
 * If you want to retrieve a particular field from all matching objects,
 * use wp_filter_object_list() instead.
 *
 * @since 3.1.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'.
 * @return array Array of found values.
 */
function wp_list_filter($list, $args = array(), $operator = 'AND')
{
    if (!is_array($list)) {
        return array();
    }
    $util = new WP_List_Util($list);
    return $util->filter($args, $operator);
}

WordPress Version: 5.1

/**
 * Filters a list of objects, based on a set of key => value arguments.
 *
 * @since 3.1.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'.
 * @return array Array of found values.
 */
function wp_list_filter($list, $args = array(), $operator = 'AND')
{
    if (!is_array($list)) {
        return array();
    }
    $util = new WP_List_Util($list);
    return $util->filter($args, $operator);
}

WordPress Version: 4.7

/**
 * Filters a list of objects, based on a set of key => value arguments.
 *
 * @since 3.1.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'.
 * @return array Array of found values.
 */
function wp_list_filter($list, $args = array(), $operator = 'AND')
{
    if (!is_array($list)) {
        return array();
    }
    $util = new WP_List_Util($list);
    return $util->filter($args, $operator);
}

WordPress Version: 4.0

/**
 * Filters a list of objects, based on a set of key => value arguments.
 *
 * @since 3.1.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. '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'.
 * @return array Array of found values.
 */
function wp_list_filter($list, $args = array(), $operator = 'AND')
{
    if (!is_array($list)) {
        return array();
    }
    if (empty($args)) {
        return $list;
    }
    $operator = strtoupper($operator);
    $count = count($args);
    $filtered = array();
    foreach ($list as $key => $obj) {
        $to_match = (array) $obj;
        $matched = 0;
        foreach ($args as $m_key => $m_value) {
            if (array_key_exists($m_key, $to_match) && $m_value == $to_match[$m_key]) {
                $matched++;
            }
        }
        if ('AND' == $operator && $matched == $count || 'OR' == $operator && $matched > 0 || 'NOT' == $operator && 0 == $matched) {
            $filtered[$key] = $obj;
        }
    }
    return $filtered;
}

WordPress Version: 3.7

/**
 * Filters a list of objects, based on a set of key => value arguments.
 *
 * @since 3.1.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:
 *    'AND' means all elements from the array must match;
 *    'OR' means only one element needs to match;
 *    'NOT' means no elements may match.
 *   The default is 'AND'.
 * @return array
 */
function wp_list_filter($list, $args = array(), $operator = 'AND')
{
    if (!is_array($list)) {
        return array();
    }
    if (empty($args)) {
        return $list;
    }
    $operator = strtoupper($operator);
    $count = count($args);
    $filtered = array();
    foreach ($list as $key => $obj) {
        $to_match = (array) $obj;
        $matched = 0;
        foreach ($args as $m_key => $m_value) {
            if (array_key_exists($m_key, $to_match) && $m_value == $to_match[$m_key]) {
                $matched++;
            }
        }
        if ('AND' == $operator && $matched == $count || 'OR' == $operator && $matched > 0 || 'NOT' == $operator && 0 == $matched) {
            $filtered[$key] = $obj;
        }
    }
    return $filtered;
}