云策 WordPress 开发者社区

钩子文档

wp_authenticate_user

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

概述

wp_authenticate_user 是一个 WordPress 过滤器钩子，用于在用户认证过程中检查用户是否可以通过提供的密码进行认证。开发者可以利用此钩子添加自定义的认证逻辑，例如验证用户状态或执行额外的安全检查。

关键要点

  • 此钩子用于过滤用户认证，允许开发者干预认证流程。
  • 参数包括 $user（WP_User 或 WP_Error 对象）和 $password（明文密码字符串）。
  • 钩子必须返回 WP_User 对象以允许认证，或返回 WP_Error 对象以拒绝认证并显示错误信息。
  • 首次引入于 WordPress 2.5.0 版本。

代码示例

/**
 * Check User Status.
 *
 * @param $user WP_User Object
 */
function check_status( WP_User $user ) {

	$status = get_user_meta( $user->ID, 'user_status', true );

	if ( 1 !== (int) $status ) {
		$message = esc_html__( 'User not verified.', 'text-domain');
		return new WP_Error( 'user_not_verified', $message );
   }

    return $user;
}

add_filter( 'wp_authenticate_user', 'check_status' );

注意事项

  • 使用 get_user_meta 时，建议设置第三个参数为 true 以获取单个值，避免返回数组导致问题。
  • 钩子传递两个参数：$user 和 $password，在自定义函数中需正确处理这些参数。
  • 要生成登录错误，必须返回一个新的 WP_Error 对象，而不是修改现有对象。
📄 原文内容

Filters whether the given user can be authenticated with the provided password.

Parameters

$userWP_User|WP_Error
WP_User or WP_Error object if a previous callback failed authentication.
$passwordstring
Password to check against the user.

More Information

This hook should return either a WP_User() object or, if generating an error, a WP_Error() object.

Source

$user = apply_filters( 'wp_authenticate_user', $user, $password );

View all references View on Trac View on GitHub

Used by Description
wp_authenticate_email_password()wp-includes/user.php

Authenticates a user using the email and password.
wp_authenticate_username_password()wp-includes/user.php

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

Changelog

Version Description
2.5.0 Introduced.

User Contributed Notes

  1. Skip to note 3 content


    Sanjeev Aryal


    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

    Example Code:

    /**
 * Check User Status.
 *
 * @param $user WP_User Object
 */
function check_status( WP_User $user ) {

	$status = get_user_meta( $user->ID, 'user_status' );

	if ( 1 !== (int) $status ) {
		$message = esc_html__( 'User not verified.', 'text-domain');
		return new WP_Error( 'user_not_verified', $message );
   }

    return $user;
}

add_filter( 'wp_authenticate_user', 'check_status' );

  2. Skip to note 4 content


    Collins Mbaka


    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

    A basic usage example

    add_filter('wp_authenticate_user', 'myplugin_auth_login',10,2);

function myplugin_auth_login ($user, $password) {
     //do any extra validation stuff here
     return $user;
}

    This hook passes two parameters, $user and $password (plaintext). In order to generate an error on login, you will need to return a new WP_Error() object.