W3cubDocs

/WordPress

wp_authenticate_username_password( WP_User|WP_Error|null $user, string $username, string $password )

Authenticate a user, confirming the username and password are valid.

Parameters

$user

(WP_User|WP_Error|null) (Required) WP_User or WP_Error object from a previous callback. Default null.

$username

(string) (Required) Username for authentication.

$password

(string) (Required) Password for authentication.

Return

(WP_User|WP_Error) WP_User on success, WP_Error on failure.

Source

File: wp-includes/user.php 

function wp_authenticate_username_password( $user, $username, $password ) {
	if ( $user instanceof WP_User ) {
		return $user;
	}

	if ( empty( $username ) || empty( $password ) ) {
		if ( is_wp_error( $user ) ) {
			return $user;
		}

		$error = new WP_Error();

		if ( empty( $username ) ) {
			$error->add( 'empty_username', __( '<strong>Error</strong>: The username field is empty.' ) );
		}

		if ( empty( $password ) ) {
			$error->add( 'empty_password', __( '<strong>Error</strong>: The password field is empty.' ) );
		}

		return $error;
	}

	$user = get_user_by( 'login', $username );

	if ( ! $user ) {
		return new WP_Error(
			'invalid_username',
			__( 'Unknown username. Check again or try your email address.' )
		);
	}

	/**
	 * Filters whether the given user can be authenticated with the provided $password.
	 *
	 * @since 2.5.0
	 *
	 * @param WP_User|WP_Error $user     WP_User or WP_Error object if a previous
	 *                                   callback failed authentication.
	 * @param string           $password Password to check against the user.
	 */
	$user = apply_filters( 'wp_authenticate_user', $user, $password );
	if ( is_wp_error( $user ) ) {
		return $user;
	}

	if ( ! wp_check_password( $password, $user->user_pass, $user->ID ) ) {
		return new WP_Error(
			'incorrect_password',
			sprintf(
				/* translators: %s: User name. */
				__( '<strong>Error</strong>: The password you entered for the username %s is incorrect.' ),
				'<strong>' . $username . '</strong>'
			) .
			' <a href="' . wp_lostpassword_url() . '">' .
			__( 'Lost your password?' ) .
			'</a>'
		);
	}

	return $user;
}

Uses

Uses Description
wp-includes/l10n.php: __()

Retrieve the translation of $text.
wp-includes/pluggable.php: wp_check_password()

Checks the plaintext password against the encrypted Password.
wp-includes/pluggable.php: get_user_by()

Retrieve user info by a given field
wp-includes/general-template.php: wp_lostpassword_url()

Returns the URL that allows the user to retrieve the lost password
wp-includes/plugin.php: apply_filters()

Calls the callback functions that have been added to a filter hook.
wp-includes/user.php: wp_authenticate_user

Filters whether the given user can be authenticated with the provided $password.
wp-includes/load.php: is_wp_error()

Check whether variable is a WordPress Error.
wp-includes/class-wp-error.php: WP_Error::__construct()

Initialize the error.

Changelog

Version Description
2.8.0 Introduced.

© 2003–2019 WordPress Foundation
Licensed under the GNU GPLv2+ License.
https://developer.wordpress.org/reference/functions/wp_authenticate_username_password