BP_User_Query
BP_User_Query Class
The BP_User_Query class was introduced in BuddyPress 1.7 as part of making BuddyPress more scalable. The class lives in buddypress/bp-core/classes/class-bp-user-query.php. Review the current class for additional arguments not listed here, such as: member types and xprofile_query.
Accepted Parameters
-
type (optional)
Defines the type of users to return.
- Accepted arguments:
active,newest,popular,online,alphabetical,random - Default value:
'newest'
- Accepted arguments:
-
per_page (optional)
The number of users to display on a page before they are paginated to the next page.
- Default value:
0
- Default value:
-
page (optional)
The page offset (together with per_page).
- Default value:
1
- Default value:
-
user_id (optional)
Pass a single numeric user id to limit results to friends of that user. Requires the Friends component.
- Default value:
0
- Default value:
-
search_terms (optional)
Terms to search by. Search happens across xprofile fields. Requires XProfile component.
- Default value:
false
- Default value:
-
include (optional)
An array or comma-separated list of user ids. Results will be limited to users in this list.
- Default value:
false
- Default value:
-
exclude (optional)
An array or comma-separated list of user ids. Results will not include any users in this list.
- Default value:
false
- Default value:
-
user_ids (optional)
An array or comma-separated list of user ids. When this parameter is passed, it will override all other parameters. BP User objects will be constructed using these IDs only. So the order of the ids will be preserved in the results.
- Default value:
false
- Default value:
-
meta_key (optional)
Limit results to users that have usermeta associated with this meta_key. Usually used with meta_value.
- Default value:
false
- Default value:
-
meta_value (optional)
When used with meta_key, limits results to users whose usermeta value associated with meta_key matches meta_value.
- Default value:
false
- Default value:
-
populate_extras (optional)
Boolean. Fetch extra meta for each user such as their full name, if they are a friend of the logged in user, their last activity time.
- Default value:
true
- Default value:
-
count_total (optional)
Determines how BP_User_Query will do a count of total users matching the other filter criteria. Default value is ‘count_query’, which does a separate SELECT COUNT query to determine the total. ‘sql_count_found_rows’ uses SQL_COUNT_FOUND_ROWS and SELECT FOUND_ROWS(). Pass an empty string to skip the total user count query.
- Default value:
'count_query'
- Default value:
Usage
This class is called by functions like bp_has_members() via bp_core_get_users().
You can create your own instance [ TO-DO: create a why and how example ].
But usually you’ll just want to manipulate the parameters.
You can do that by using this hook in the class:
do_action_ref_array( 'bp_pre_user_query_construct', array( &$this ) ); //$this is a reference to the parameter array
Code Examples
Here’s an example using the bp_pre_user_query_construct hook. This example will affect the display of members on the Members page by not showing any of the members whose ids are in $this->custom_ids. It will not affect the display of members on pages like .../groups/some-group/members/ or in widgets, etc. We use the bp_before_directory_members hook instead of one of the other hooks, like bp_before_members_loop, because we want to adjust the ‘All Members’ count too. Using this approach, we do not have to touch any template files.
class BP_Custom_User_Ids { private $custom_ids = array(); public function __construct() { $this->custom_ids = $this->get_custom_ids(); add_action( 'bp_pre_user_query_construct', array( $this, 'custom_members_query' ), 1, 1 ); add_filter( 'bp_get_total_member_count', array( $this, 'custom_members_count' ), 1, 1 ); } private function get_custom_ids() { global $wpdb; // collection based on an xprofile field $custom_ids = $wpdb->get_col("SELECT user_id FROM {$wpdb->prefix}bp_xprofile_data WHERE field_id = 8 AND value = 'no'"); return $custom_ids; } function custom_members_query( $query_array ) { $query_array->query_vars['exclude'] = $this->custom_ids; //in case there are other items like widgets using the members loop on the members page remove_action( 'bp_pre_user_query_construct', array( $this, 'custom_members_query' ), 1, 1 ); } function custom_members_count ( $count ) { $new_count = count( $this->custom_ids ); return $count - $new_count; } } function custom_user_ids( ) { new BP_Custom_User_Ids (); } add_action( 'bp_before_directory_members', 'custom_user_ids' );Preserve the Order
Have you ever wanted to preserve the order of ids passed into the members loop? Now you can by using the ‘user_ids’ parameter:function custom_members_query( $query_array ) { $query_array->query_vars['user_ids'] = $this->custom_ids; }NB: the ‘user_ids’ parameter will break pagination in versions less than BP 1.9. Ticket & Patch
Additional Resources
class BP_Group_Member_Query extends BP_User_Query
In most situations, bp_parse_args() is a better and easier approach to filtering members: Using bp_parse_args() to filter BuddyPress template loops/
