bp_core_get_users( array|string $args = '' )

Fetch an array of users based on the parameters passed.


Description Description

Since BuddyPress 1.7, bp_core_get_users() uses BP_User_Query. If you need backward compatibility with BP_Core_User::get_users(), filter the bp_use_legacy_user_query value, returning true.


Top ↑

Parameters Parameters

$args

(array|string) (Optional) Array of arguments. All are optional. See BP_User_Query for a more complete description of arguments.

  • 'type'
    (string) Sort order. Default: 'active'.
  • 'user_id'
    (int) Limit results to friends of a user. Default: false.
  • 'exclude'
    (mixed) IDs to exclude from results. Default: false.
  • 'search_terms'
    (string) Limit to users matching search terms. Default: false.
  • 'meta_key'
    (string) Limit to users with a meta_key. Default: false.
  • 'meta_value'
    (string) Limit to users with a meta_value (with meta_key). Default: false.
  • 'member_type'
    (array|string) Array or comma-separated string of member types.
  • 'member_type__in'
    (array|string) Array or comma-separated string of member types. $member_type takes precedence over this parameter.
  • 'member_type__not_in'
    (array|string) Array or comma-separated string of member types to be excluded.
  • 'include'
    (mixed) Limit results by user IDs. Default: false.
  • 'user_ids'
    (mixed) IDs corresponding to the users. Default: false.
  • 'per_page'
    (int) Results per page. Default: 20.
  • 'page'
    (int) Page of results. Default: 1.
  • 'populate_extras'
    (bool) Fetch optional extras. Default: true.
  • 'xprofile_query'
    (array) Filter results by xprofile data. Requires the xprofile component. See BP_XProfile_Query for details.
  • 'count_total'
    (string|bool) How to do total user count. Default: 'count_query'.

Default value: ''


Top ↑

Return Return

(array)


Source Source

File: bp-members/bp-members-functions.php

function bp_core_get_users( $args = '' ) {

	// Parse the user query arguments.
	$r = bp_parse_args( $args, array(
		'type'                => 'active',     // Active, newest, alphabetical, random or popular.
		'user_id'             => false,        // Pass a user_id to limit to only friend connections for this user.
		'exclude'             => false,        // Users to exclude from results.
		'search_terms'        => false,        // Limit to users that match these search terms.
		'meta_key'            => false,        // Limit to users who have this piece of usermeta.
		'meta_value'          => false,        // With meta_key, limit to users where usermeta matches this value.
		'member_type'         => '',
		'member_type__in'     => '',
		'member_type__not_in' => '',
		'include'             => false,        // Pass comma separated list of user_ids to limit to only these users.
		'user_ids'            => false,
		'per_page'            => 20,           // The number of results to return per page.
		'page'                => 1,            // The page to return if limiting per page.
		'populate_extras'     => true,         // Fetch the last active, where the user is a friend, total friend count, latest update.
		'xprofile_query'      => false,
		'count_total'         => 'count_query' // What kind of total user count to do, if any. 'count_query', 'sql_calc_found_rows', or false.
	), 'core_get_users' );

	/**
	 * For legacy users. Use of BP_Core_User::get_users() is deprecated.
	 *
	 * Forcing this filter to true will use the legacy user query. As of
	 * BuddyPress 7.0.0, mirroring of the 'last_activity' value to usermeta
	 * is also disabled if true. See bp_update_user_last_activity().
	 *
	 * @since 2.0.0
	 *
	 * @param bool   $retval   Defaults to false.
	 * @param string $function Current function name.
	 * @param array  $r        User query arguments.
	 */
	$use_legacy_query = apply_filters( 'bp_use_legacy_user_query', false, __FUNCTION__, $r );

	if ( $use_legacy_query ) {
		$retval = BP_Core_User::get_users(
			$r['type'],
			$r['per_page'],
			$r['page'],
			$r['user_id'],
			$r['include'],
			$r['search_terms'],
			$r['populate_extras'],
			$r['exclude'],
			$r['meta_key'],
			$r['meta_value']
		);

	// Default behavior as of BuddyPress 1.7.0.
	} else {

		// Get users like we were asked to do...
		$users = new BP_User_Query( $r );

		// ...but reformat the results to match bp_core_get_users() behavior.
		$retval = array(
			'users' => array_values( $users->results ),
			'total' => $users->total_users
		);
	}

	/**
	 * Filters the results of the user query.
	 *
	 * @since 1.2.0
	 *
	 * @param array $retval Array of users for the current query.
	 * @param array $r      Array of parsed query arguments.
	 */
	return apply_filters( 'bp_core_get_users', $retval, $r );
}


Top ↑

Changelog Changelog

Changelog
Version Description
7.0.0 Added xprofile_query parameter. Added user_ids parameter.
1.2.0 Introduced.

Top ↑

User Contributed Notes User Contributed Notes

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