wp_authenticate
Authenticate a user, confirming the login credentials are valid.
Description
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
if ( !function_exists( 'wp_authenticate' ) ) { require_once ABSPATH . WPINC . '/pluggable.php'; } // User's username or email address. $username = ''; // User's password. $password = ''; // NOTICE! Understand what this does before running. $result = wp_authenticate($username, $password);
Defined (1)
The function is defined in the following location(s).
- /wp-includes/pluggable.php
- function wp_authenticate($username, $password) {
- $username = sanitize_user($username);
- $password = trim($password);
- /**
- * Filters whether a set of user login 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 ( $user == null ) {
- // TODO what should theerrormessage be? (Or would these even happen?)
- // Only needed if all authentication handlers fail to return anything.
- }
- $ignore_codes = array('empty_username', 'empty_password');
- if (is_wp_error($user) && !in_array($user->get_error_code(), $ignore_codes) ) {
- /**
- * Fires after a user login has failed.
- *
- * @since 2.5.0
- * @since 4.5.0 The value of `$username` can now be an email address.
- *
- * @param string $username Username or email address.
- */
- do_action( 'wp_login_failed', $username );
- }
- return $user;
- }