apply_filters( 'user_search_columns', string[] $search_columns, string $search, WP_User_Query $this )

Filters the columns to search in a WP_User_Query search.


Description Description

The default columns depend on the search term, and include ‘ID’, ‘user_login’, ‘user_email’, ‘user_url’, ‘user_nicename’, and ‘display_name’.


Top ↑

Parameters Parameters

$search_columns

(string[]) Array of column names to be searched.

$search

(string) Text being searched.

$this

(WP_User_Query) The current WP_User_Query instance.


Top ↑

More Information More Information

The user_search_columns filter is used to determine which user fields in the database are used when performing a search on user information.

 

When the ‘user_search_columns’ filter is called, it is passed three parameters: an array of fields to search, the search term, WP_User_Query object

<pre>add_filter( 'user_search_columns', 'filter_function_name', 10, 3 );

function filter_function_name( $search_columns, $search, $wp_user_query ) {
    // Alter $search_columns to include the fields you want to search on
    return $search_columns;
}

Where ‘filter_function_name’ is the function WordPress should call when the filter is run. Note that the filter function must return a value after it is finished processing or the search terms will be empty.

filter_function_name should be unique function name. It cannot match any other function name already declared


Top ↑

Source Source

File: wp-includes/class-wp-user-query.php

View on Trac



Top ↑

Changelog Changelog

Changelog
Version Description
3.6.0 Introduced.

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    Contributed by Collins Mbaka

    Add a field to search on

    In this example, the user’s URL is also added to the list of columns searched

    add_filter( 'user_search_columns', 'wpdocs_filter_function_name', 10, 3 );
        
    function wpdocs_filter_function_name( $search_columns, $search, $wp_user_query ) {
        $search_columns[] = 'user_url';
        return $search_columns;
    }
    
  2. Skip to note 2 content
    Contributed by Collins Mbaka

    Alter search fields based on the search term

    In this example, if the user searches for something with ‘.com’ in it only the user_url field will be searched

    add_filter( 'user_search_columns', 'wpdocs_filter_function_name', 10, 2 );
    
    function wpdocs_filter_function_name( $search_columns, $search ) {
        $val = strpos( $search, '.com' );
        
        if ( false !== $val ) {
    	    $search_columns = array( 'user_url' );
        }
        
        return $search_columns;
    }
    
  3. Skip to note 3 content
    Contributed by Akira Tachibana

    (From Codex)
    Add a field to search on
    In this example the user’s URL is also added to the list of columns searched

    add_filter( 'user_search_columns', 'filter_function_name', 10, 3 );
        
    function filter_function_name( $search_columns, $search, $wp_user_query ) {
        $search_columns[] = 'user_url';
        return $search_columns;
    }
  4. Skip to note 4 content
    Contributed by Akira Tachibana

    (From Codex)
    Alter search fields based on search term

    In this example if the user searches for something with ‘.com’ in it only the user_url field will be searched.

    add_filter( 'user_search_columns', 'filter_function_name', 10, 3 );
    
    function filter_function_name( $search_columns, $search, $wp_user_query ) {
        $val = strpos($search, '.com');
        
        if( $val !== false ) {
    	    $search_columns = array('user_url');
        }
        
        return $search_columns;
    }

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