get_user_by( string $field, int|string $value ): WP_User|false

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$fieldstring

The field to retrieve the user with. id | ID | slug | email | login.

$valueint|string

A value for $field. A user ID, slug, email address, or login name.

Return value

WP_User|false

WP_User object on success, false on failure.

Code examples

Every example is editable and runs in a real WordPress booted in your browser by WordPress Playground. Press Run, then edit the code: clicking away re-runs it. Nothing is sent anywhere until you do.

$new_user_id = wp_insert_user( array(
	'user_login' => 'reviewer',
	'user_email' => '[email protected]',
	'user_pass'  => wp_generate_password(),
) );

$user = get_user_by( 'email', '[email protected]' );

if ( $user ) {
	echo esc_html( 'Found user: ' . $user->display_name . ' (ID ' . $user->ID . ')' );
} else {
	echo esc_html( 'No user found with that email.' );
}

$current_id = get_current_user_id();
$user       = get_user_by( 'id', $current_id );

if ( $user ) {
	echo esc_html( 'Logged in as: ' . $user->user_login . ', role: ' . implode( ', ', $user->roles ) );
} else {
	echo esc_html( 'No user is logged in.' );
}

Common problems and fixes · 3

• Why does get_user_by return false even though the account exists?
• Can I pass an array to look up several users at once?
• Is it safe to pass a raw $_GET or $_POST value as $value?

Alternatives and related functions

get_userdata

When you only ever look up a user by numeric ID, get_userdata() is a shorter call that does the same thing.

get_users

When you need a list of users matching criteria instead of a single account by one field.

wp_get_current_user

When you want the currently logged-in user rather than looking one up by ID, slug, email, or login.

WP_User_Query

When the lookup needs pagination, role filtering, or meta query conditions beyond a single field match.

Performance profile

How much work a call to get_user_by() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Trivial

Reaches the database via get_user_by().

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

9–15

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 16.

Plugin surface

None

Nothing here hands control to plugin code.

Called by

44

44 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• querycontent queryget_user_by()this function does it

What one call costs · 2 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost get_user_by() can have, taken from its control-flow graph on PHP 8.5.

Uses · 2

• WP_User::get_data_by()Returns only the main user fields.
• WP_User::__construct()Constructor.

Used by · 44

• WP_Automatic_Updater::send_debug_email()Prepares and sends an email of a full log of background update results, useful for debugging and geekery.
• WP_Automatic_Updater::send_email()Sends an email upon the completion or failure of a background core update.
• WP_Automatic_Updater::send_plugin_theme_email()Sends an email upon the completion or failure of a plugin or theme background update.
• WP_Query::get_posts()Retrieves an array of posts based on query variables.
• WP_Query::get_queried_object()Retrieves the currently queried object.
• WP_REST_Templates_Controller::get_wp_templates_author_text_field()Returns a human readable text for the author of the template.
• WP_REST_Users_Controller::create_item()Creates a single user.
• WP_REST_Users_Controller::update_item()Updates a single user.
• _wp_get_entity_view_config_posttype_wp_template()Provides the view configuration for the `wp_template` post type.
• _wp_personal_data_handle_actions()Handle list table actions.
• check_comment()Checks whether a comment passes internal checks to be allowed to add.
• check_password_reset_key()Retrieves a user row based on password reset key and login.

Source code

View on Trac ↗View on GitHub ↗

101	function get_user_by( $field, $value ) {102		$userdata = WP_User::get_data_by( $field, $value );103 104		if ( ! $userdata ) {105			return false;106		}107 108		$user = new WP_User();109		$user->init( $userdata );110 111		return $user;112	}

Changelog

Introduced in 2.8.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 7.1.0 tag, from src/wp-includes/pluggable.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.