BP_Core_User::get_users_by_letter( string $letter, int|null $limit = null, int $page = 1, bool $populate_extras = true, string $exclude = '' )

Fetch the details for all users whose usernames start with the given letter.

Description

Parameters

$letter

(string) (Required) The letter the users names are to start with.

$limit

(int|null) (Optional) The number of users we wish to retrive.

Default value: null

$page

(int) (Optional) The page number we are currently on, used in conjunction with $limit to get the start position for the limit.

Default value: 1

$populate_extras

(bool) (Optional) If we should populate extra user fields.

Default value: true

$exclude

(string) (Optional) Comma-separated IDs of users whose results aren't to be fetched.

Default value: ''

Return

(false|array) False on error, otherwise associative array of results.

Source

File: bp-core/classes/class-bp-core-user.php

	public static function get_users_by_letter( $letter, $limit = null, $page = 1, $populate_extras = true, $exclude = '' ) {
		global $wpdb;

		$pag_sql = '';
		if ( $limit && $page ) {
			$pag_sql = $wpdb->prepare( " LIMIT %d, %d", intval( ( $page - 1 ) * $limit), intval( $limit ) );
		}

		// Multibyte compliance.
		if ( function_exists( 'mb_strlen' ) ) {
			if ( mb_strlen( $letter, 'UTF-8' ) > 1 || is_numeric( $letter ) || !$letter ) {
				return false;
			}
		} else {
			if ( strlen( $letter ) > 1 || is_numeric( $letter ) || !$letter ) {
				return false;
			}
		}

		$bp = buddypress();

		$letter_like = bp_esc_like( $letter ) . '%';
		$status_sql  = bp_core_get_status_sql( 'u.' );

		if ( !empty( $exclude ) ) {
			$exclude     = implode( ',', wp_parse_id_list( $exclude ) );
			$exclude_sql = " AND u.id NOT IN ({$exclude})";
		} else {
			$exclude_sql = '';
		}

		/**
		 * Filters the SQL used to query for total user count by first letter.
		 *
		 * @since BuddyPress 1.0.0
		 *
		 * @param string $value SQL prepared statement for the user count query.
		 */
		$total_users_sql = apply_filters( 'bp_core_users_by_letter_count_sql', $wpdb->prepare( "SELECT COUNT(DISTINCT u.ID) FROM {$wpdb->users} u LEFT JOIN {$bp->profile->table_name_data} pd ON u.ID = pd.user_id LEFT JOIN {$bp->profile->table_name_fields} pf ON pd.field_id = pf.id WHERE {$status_sql} AND pf.name = %s {$exclude_sql} AND pd.value LIKE %s ORDER BY pd.value ASC", bp_xprofile_fullname_field_name(), $letter_like ) );

		/**
		 * Filters the SQL used to query for users by first letter.
		 *
		 * @since BuddyPress 1.0.0
		 *
		 * @param string $value SQL prepared statement for the user query.
		 */
		$paged_users_sql = apply_filters( 'bp_core_users_by_letter_sql',       $wpdb->prepare( "SELECT DISTINCT u.ID as id, u.user_registered, u.user_nicename, u.user_login, u.user_email FROM {$wpdb->users} u LEFT JOIN {$bp->profile->table_name_data} pd ON u.ID = pd.user_id LEFT JOIN {$bp->profile->table_name_fields} pf ON pd.field_id = pf.id WHERE {$status_sql} AND pf.name = %s {$exclude_sql} AND pd.value LIKE %s ORDER BY pd.value ASC{$pag_sql}", bp_xprofile_fullname_field_name(), $letter_like ) );

		$total_users = $wpdb->get_var( $total_users_sql );
		$paged_users = $wpdb->get_results( $paged_users_sql );

		/**
		 * Lets fetch some other useful data in a separate queries, this will be
		 * faster than querying the data for every user in a list. We can't add
		 * these to the main query above since only users who have this
		 * information will be returned (since the much of the data is in
		 * usermeta and won't support any type of directional join)
		 */
		$user_ids = array();
		foreach ( (array) $paged_users as $user )
			$user_ids[] = (int) $user->id;

		// Add additional data to the returned results.
		if ( $populate_extras ) {
			$paged_users = BP_Core_User::get_user_extras( $paged_users, $user_ids );
		}

		return array( 'users' => $paged_users, 'total' => $total_users );
	}

Questions?

We're always happy to help with code or other questions you might have! Search our developer docs, contact support, or connect with our sales team.