云策 WordPress 开发者社区

钩子文档

authenticate

查看官方原文 ↗
💡 云策文档标注

概述

authenticate 过滤器用于在用户登录 WordPress 时验证登录凭据的有效性，允许开发者自定义认证逻辑。它返回 WP_User 对象表示认证成功，否则返回 WP_Error 或 null。

关键要点

  • authenticate 过滤器在用户登录过程中执行，用于添加额外的验证或认证步骤。
  • 参数包括 $user（初始为 null，认证成功时返回 WP_User，失败时返回 WP_Error 或 null）、$username（用户名或邮箱地址）和 $password（密码）。
  • WordPress 默认添加了多个 authenticate 过滤器，如 wp_authenticate_username_password 和 wp_authenticate_email_password。
  • wp_authenticate_user 过滤器可在 WordPress 基础验证之后、用户登录之前使用。
  • 从版本 4.5.0 开始，$username 参数接受邮箱地址。

代码示例

add_filter( 'authenticate', 'myplugin_auth_signon', 30, 3 );
function myplugin_auth_signon( $user, $username, $password ) {
     return $user;
}
function wpdocs_authenticate_user( $user, $username, $password ) {
	if ( empty( $username ) || empty( $password ) ) {
		$error = new WP_Error();
		$user  = new WP_Error( 'authentication_failed', __( 'ERROR: Invalid username or incorrect password.' ) );
		return $error;
	}

	return $user;
}
add_filter( 'authenticate', 'wpdocs_authenticate_user', 10, 3 );

注意事项

  • 返回 WP_Error 对象可在登录失败时生成错误信息，返回 null 则 WordPress 会分配标准 WP_Error。
  • 示例代码展示了如何检查用户名和密码是否为空，并返回自定义错误。
📄 原文内容

Filters whether a set of user login credentials are valid.

Description

A WP_User object is returned if the credentials authenticate a user.
WP_Error or null otherwise.

Parameters

$usernull|WP_User|WP_Error
WP_User if the user is authenticated.
WP_Error or null otherwise.
$usernamestring
Username or email address.
$passwordstring
User password.

More Information

The authenticate filter hook is used to perform additional validation/authentication any time a user logs in to WordPress.

The wp_authenticate_user filter can also be used if you want to perform any additional validation after WordPress’s basic validation, but before a user is logged in.

The default authenticate filters in /wp-includes/default-filters.php

add_filter( 'authenticate', 'wp_authenticate_username_password',  20, 3 );
add_filter( 'authenticate', 'wp_authenticate_email_password',     20, 3 );
add_filter( 'authenticate', 'wp_authenticate_spam_check',         99    );

Source

$user = apply_filters( 'authenticate', null, $username, $password );

View all references View on Trac View on GitHub

Used by Description
wp_authenticate()wp-includes/pluggable.php

Authenticates a user, confirming the login credentials are valid.

Changelog

Version Description
4.5.0 $username now accepts an email address.
2.8.0 Introduced.

User Contributed Notes

  1. Skip to note 4 content


    Rahul Prajapati


    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    ==Examples==
    The basic usage is as follows…

    add_filter( 'authenticate', 'myplugin_auth_signon', 30, 3 );
function myplugin_auth_signon( $user, $username, $password ) {
     return $user;
}

    This hook passes three parameters, $user, $username and $password. In order to generate an error on login, you will need to return a WP_Error object.

  2. Skip to note 5 content


    Dragi Postolovski


    You must log in to vote on the helpfulness of this noteVote results for this note: -1You must log in to vote on the helpfulness of this note

    function wpdocs_authenticate_user( $user, $username, $password ) {
	if ( empty( $username ) || empty( $password ) ) {
		$error = new WP_Error();
		$user  = new WP_Error( 'authentication_failed', __( 'ERROR: Invalid username or incorrect password.' ) );
		return $error;
	}

	return $user;
}
add_filter( 'authenticate', 'wpdocs_authenticate_user', 10, 3 );

    Goes nicely with:

    public function wpdocs_login_form_failed( $username ) {
	// append some information (login=failed) to the URL
	wp_redirect( home_url() . '/?login=failed' );
	exit;
}

add_action( 'wp_login_failed', 'wpdocs_login_form_failed' );

  3. Skip to note 6 content


    pronl


    You must log in to vote on the helpfulness of this noteVote results for this note: -2You must log in to vote on the helpfulness of this note

    … or simply return null.

    WordPress will assign a standard WP_Error object:

    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.' ) );
}