wp_authenticate

The timeline below displays how wordpress function wp_authenticate has changed across different WordPress versions. If a version is not listed, refer to the next available version below.

WordPress Version: 6.3

/**
 * Authenticates a user, confirming the login credentials are valid.
 *
 * @since 2.5.0
 * @since 4.5.0 `$username` now accepts an email address.
 *
 * @param string $username User's username or email address.
 * @param string $password User's password.
 * @return WP_User|WP_Error WP_User object if the credentials are valid,
 *                          otherwise WP_Error.
 */
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 (null == $user) {
        /*
         * TODO: What should the error message 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->get_error_code(), $ignore_codes, true)) {
        $error = $user;
        /**
         * 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.
         * @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_login_failed', $username, $error);
    }
    return $user;
}

WordPress Version: 6.1

/**
 * Authenticates a user, confirming the login credentials are valid.
 *
 * @since 2.5.0
 * @since 4.5.0 `$username` now accepts an email address.
 *
 * @param string $username User's username or email address.
 * @param string $password User's password.
 * @return WP_User|WP_Error WP_User object if the credentials are valid,
 *                          otherwise WP_Error.
 */
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 (null == $user) {
        // TODO: What should the error message 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->get_error_code(), $ignore_codes, true)) {
        $error = $user;
        /**
         * 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.
         * @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_login_failed', $username, $error);
    }
    return $user;
}

WordPress Version: 5.5

/**
 * Authenticate a user, confirming the login credentials are valid.
 *
 * @since 2.5.0
 * @since 4.5.0 `$username` now accepts an email address.
 *
 * @param string $username User's username or email address.
 * @param string $password User's password.
 * @return WP_User|WP_Error WP_User object if the credentials are valid,
 *                          otherwise WP_Error.
 */
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 (null == $user) {
        // TODO: What should the error message 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->get_error_code(), $ignore_codes, true)) {
        $error = $user;
        /**
         * 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.
         * @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_login_failed', $username, $error);
    }
    return $user;
}

WordPress Version: 5.4

/**
 * Authenticate a user, confirming the login credentials are valid.
 *
 * @since 2.5.0
 * @since 4.5.0 `$username` now accepts an email address.
 *
 * @param string $username User's username or email address.
 * @param string $password User's password.
 * @return WP_User|WP_Error WP_User object if the credentials are valid,
 *                          otherwise WP_Error.
 */
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 (null == $user) {
        // TODO: What should the error message 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->get_error_code(), $ignore_codes)) {
        $error = $user;
        /**
         * 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.
         * @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_login_failed', $username, $error);
    }
    return $user;
}

WordPress Version: 4.6

/**
 * Authenticate a user, confirming the login credentials are valid.
 *
 * @since 2.5.0
 * @since 4.5.0 `$username` now accepts an email address.
 *
 * @param string $username User's username or email address.
 * @param string $password User's password.
 * @return WP_User|WP_Error WP_User object if the credentials are valid,
 *                          otherwise WP_Error.
 */
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 the error message 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->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;
}

WordPress Version: 4.5

/**
 * Authenticate a user, confirming the login credentials are valid.
 *
 * @since 2.5.0
 * @since 4.5.0 `$username` now accepts an email address.
 *
 * @param string $username User's username or email address.
 * @param string $password User's password.
 * @return WP_User|WP_Error WP_User object if the credentials are valid,
 *                          otherwise WP_Error.
 */
function wp_authenticate($username, $password)
{
    $username = sanitize_user($username);
    $password = trim($password);
    /**
     * Filter 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 the error message 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->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;
}

WordPress Version: 3.9

/**
 * Checks a user's login information and logs them in if it checks out.
 *
 * @since 2.5.0
 *
 * @param string $username User's username
 * @param string $password User's password
 * @return WP_User|WP_Error WP_User object if login successful, otherwise WP_Error object.
 */
function wp_authenticate($username, $password)
{
    $username = sanitize_user($username);
    $password = trim($password);
    /**
     * Filter the user to authenticate.
     *
     * If a non-null value is passed, the filter will effectively short-circuit
     * authentication, returning an error instead.
     *
     * @since 2.8.0
     *
     * @param null|WP_User $user     User to authenticate.
     * @param string       $username User login.
     * @param string       $password User password
     */
    $user = apply_filters('authenticate', null, $username, $password);
    if ($user == null) {
        // TODO what should the error message 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 or incorrect password.'));
    }
    $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
         *
         * @param string $username User login.
         */
        do_action('wp_login_failed', $username);
    }
    return $user;
}

WordPress Version: 3.7

/**
 * Checks a user's login information and logs them in if it checks out.
 *
 * @since 2.5.0
 *
 * @param string $username User's username
 * @param string $password User's password
 * @return WP_User|WP_Error WP_User object if login successful, otherwise WP_Error object.
 */
function wp_authenticate($username, $password)
{
    $username = sanitize_user($username);
    $password = trim($password);
    $user = apply_filters('authenticate', null, $username, $password);
    if ($user == null) {
        // TODO what should the error message 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 or incorrect password.'));
    }
    $ignore_codes = array('empty_username', 'empty_password');
    if (is_wp_error($user) && !in_array($user->get_error_code(), $ignore_codes)) {
        do_action('wp_login_failed', $username);
    }
    return $user;
}