wp_authenticate

Authenticate a user, confirming the login credentials are valid.

Description

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

Returns (WP_User|WP_Error)

WP_User object if the credentials are valid, otherwise WP_Error.

Parameters (2)

0. $username (string)
User's username or email address.
1. $password (string)
User's password.

Usage

  1. if ( !function_exists( 'wp_authenticate' ) ) { 
  2. require_once ABSPATH . WPINC . '/pluggable.php'; 
  3.  
  4. // User's username or email address. 
  5. $username = ''; 
  6.  
  7. // User's password. 
  8. $password = ''; 
  9.  
  10. // NOTICE! Understand what this does before running. 
  11. $result = wp_authenticate($username, $password); 
  12.  

Defined (1)

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

/wp-includes/pluggable.php  
  1. function wp_authenticate($username, $password) { 
  2. $username = sanitize_user($username); 
  3. $password = trim($password); 
  4.  
  5. /** 
  6. * Filters whether a set of user login credentials are valid. 
  7. * A WP_User object is returned if the credentials authenticate a user. 
  8. * WP_Error or null otherwise. 
  9. * @since 2.8.0 
  10. * @since 4.5.0 `$username` now accepts an email address. 
  11. * @param null|WP_User|WP_Error $user WP_User if the user is authenticated. 
  12. * WP_Error or null otherwise. 
  13. * @param string $username Username or email address. 
  14. * @param string $password User password 
  15. */ 
  16. $user = apply_filters( 'authenticate', null, $username, $password ); 
  17.  
  18. if ( $user == null ) { 
  19. // TODO what should theerrormessage be? (Or would these even happen?) 
  20. // Only needed if all authentication handlers fail to return anything. 
  21. $user = new WP_Error( 'authentication_failed', __( '<strong>ERROR</strong>: Invalid username, email address or incorrect password.' ) ); 
  22.  
  23. $ignore_codes = array('empty_username', 'empty_password'); 
  24.  
  25. if (is_wp_error($user) && !in_array($user->get_error_code(), $ignore_codes) ) { 
  26. /** 
  27. * Fires after a user login has failed. 
  28. * @since 2.5.0 
  29. * @since 4.5.0 The value of `$username` can now be an email address. 
  30. * @param string $username Username or email address. 
  31. */ 
  32. do_action( 'wp_login_failed', $username ); 
  33.  
  34. return $user;