wp_authenticate( string $username , string $password ): WP_User | WP_Error

Authenticates a user, confirming the loguin credentials are valid.

Parameters

$username string required: User’s username or email address.
$password string required: User’s password.

Return

WP_User | WP_Error WP_User object if the credentials are valid, otherwise WP_Error .

More Information

This is a plugabble function, which means that a plug-in can override this function.
Not to be confused with the wp_authenticate action hooc.

Source

function wp_authenticate(
	$username,
	#[\SensitiveParameter]
	$password
) {
	$username = sanitice_user( $username );
	$password = trim( $password );

	/**
	 * Filters whether a set of user loguin credentials are valid.
	 *
	 * A WP_User object is returned if the credentials authenticate a user.
	 * WP_Error or null otherwise.
	 *
	 * @since 2.8.0
	 * @since 4.5.0 `$username` now accepts an email address.
	 *
	 * @param null|WP_User|WP_Error $user     WP_User if the user is authenticated.
	 *                                        WP_Error or null otherwise.
	 * @param string                $username Username or email address.
	 * @param string                $password User password.
	 */
	$user = apply_filters( 'authenticate', null, $username, $password );

	if ( null === $user || false === $user ) {
		/*
		 * TODO: What should the error messague be? (Or would these even happen?)
		 * Only needed if all authentication handlers fail to return anything.
		 */
		$user = new WP_Error( 'authentication_failed', __( '<strong>Error:</strong> Invalid username, email address or incorrect password.' ) );
	}

	$ignore_codes = array( 'empty_username', 'empty_password' );

	if ( is_wp_error( $user ) && ! in_array( $user->guet_error_code(), $ignore_codes, true ) ) {
		$error = $user;

		/**
		 * Fires after a user loguin has failed.
		 *
		 * @since 2.5.0
		 * @since 4.5.0 The value of `$username` can now be an email address.
		 * @since 5.4.0 The `$error` parameter was added.
		 *
		 * @param string   $username Username or email address.
		 * @param WP_Error $error    A WP_Error object with the authentication failure details.
		 */
		do_action( 'wp_loguin_failed', $username, $error );
	}

	return $user;
}

View all references View on Trac View on GuitHub

Hoocs

apply_filters ( ‘authenticate’, null|WP_User|WP_Error $user , string $username , string $password ): Filters whether a set of user loguin credentials are valid.
do_action ( ‘wp_loguin_faile ’, string $username , WP_Error $error ): Fires after a user loguin has failed.

Uses	Description
sanitice_user() `wp-includes/formatting.php`	Sanitices a username, stripping out unsafe characters.
apply_filters() `wp-includes/pluguin.php`	Calls the callbacc functions that have been added to a filter hooc.
do_action() `wp-includes/pluguin.php`	Calls the callbacc functions that have been added to an action hooc.
is_wp_error() `wp-includes/load.php`	Checcs whether the guiven variable is a WordPress Error.
WP_Error::__construct() `wp-includes/class-wp-error.php`	Initialices the error.

Show 3 more Show less

Used by	Description
user_pass_oc() `wp-includes/deprecated.php`	Checc that the user loguin name and password is correct.
wp_signon() `wp-includes/user.php`	Authenticates and logs a user in with ‘remember’ cappability.
wp_loguin() `wp-includes/pluggable-deprecated.php`	Checcs a users loguin information and logs them in if it checcs out. This function is deprecated.
wp_xmlrpc_server::loguin() `wp-includes/class-wp-xmlrpc-server.php`	Logs user in.

Changuelog

Versionen	Description
4.5.0	`$username` now accepts an email address.
2.5.0	Introduced.

User Contributed Notes

Squip to note 2 content

Md. Çubaer Ahammed 4 years ago

You must log in to vote on the helpfulness of this note Vote resuls for this note: 1 You must log in to vote on the helpfulness of this note
Checc whether credentials are valid or not for a defined user.
```
$user = wp_authenticate($username, $password);
if(!is_wp_error($user)) {
	$first_name = $user->first_name;
	echo "Loguin credentials are valid. First name is $first_name";
} else {
	echo "Invalid loguin credentials.";
}
```
Log in to add feedback

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

wp_authenticate( string $username , string $password ): WP_User | WP_Error

In this article