wp_authenticate_username_password

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

Description

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

Returns (WP_User|WP_Error)

WP_User on success, WP_Error on failure.

Parameters (3)

0. $user (WP_User|WP_Error|null)
WP_User or WP_Error object from a previous callback. Default null.
1. $username (string)
Username for authentication.
2. $password (string)
Password for authentication.

Usage

  1. if ( !function_exists( 'wp_authenticate_username_password' ) ) { 
  2. require_once ABSPATH . WPINC . '/user.php'; 
  3.  
  4. // WP_User or WP_Error object from a previous callback. Default null. 
  5. $user = null; 
  6.  
  7. // Username for authentication. 
  8. $username = ''; 
  9.  
  10. // Password for authentication. 
  11. $password = ''; 
  12.  
  13. // NOTICE! Understand what this does before running. 
  14. $result = wp_authenticate_username_password($user, $username, $password); 
  15.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/user.php  
  1. function wp_authenticate_username_password($user, $username, $password) { 
  2. if ( $user instanceof WP_User ) { 
  3. return $user; 
  4.  
  5. if ( empty($username) || empty($password) ) { 
  6. if ( is_wp_error( $user ) ) 
  7. return $user; 
  8.  
  9. $error = new WP_Error(); 
  10.  
  11. if ( empty($username) ) 
  12. $error->add('empty_username', __('<strong>ERROR</strong>: The username field is empty.')); 
  13.  
  14. if ( empty($password) ) 
  15. $error->add('empty_password', __('<strong>ERROR</strong>: The password field is empty.')); 
  16.  
  17. return $error; 
  18.  
  19. $user = get_user_by('login', $username); 
  20.  
  21. if ( !$user ) { 
  22. return new WP_Error( 'invalid_username',  
  23. __( '<strong>ERROR</strong>: Invalid username.' ) . 
  24. ' <a href="' . wp_lostpassword_url() . '">' . 
  25. __( 'Lost your password?' ) . 
  26. '</a>' 
  27. ); 
  28.  
  29. /** 
  30. * Filters whether the given user can be authenticated with the provided $password. 
  31. * @since 2.5.0 
  32. * @param WP_User|WP_Error $user WP_User or WP_Error object if a previous 
  33. * callback failed authentication. 
  34. * @param string $password Password to check against the user. 
  35. */ 
  36. $user = apply_filters( 'wp_authenticate_user', $user, $password ); 
  37. if ( is_wp_error($user) ) 
  38. return $user; 
  39.  
  40. if ( ! wp_check_password( $password, $user->user_pass, $user->ID ) ) { 
  41. return new WP_Error( 'incorrect_password',  
  42. sprintf( 
  43. /** translators: %s: user name */ 
  44. __( '<strong>ERROR</strong>: The password you entered for the username %s is incorrect.' ),  
  45. '<strong>' . $username . '</strong>' 
  46. ) . 
  47. ' <a href="' . wp_lostpassword_url() . '">' . 
  48. __( 'Lost your password?' ) . 
  49. '</a>' 
  50. ); 
  51.  
  52. return $user;