云策 WordPress 开发者社区

钩子文档

registration_errors

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

概述

registration_errors 是一个 WordPress 过滤器钩子，用于在新用户注册过程中过滤遇到的错误。它允许开发者添加自定义验证规则，并在表单提交后、用户信息保存到数据库前执行。

关键要点

  • 该过滤器接收一个 WP_Error 对象、已清理的用户名和用户邮箱作为参数，必须始终返回 WP_Error 对象，即使没有错误。
  • 如果 $errors 中包含任何错误，将中止用户注册过程。
  • 可用于创建自定义验证规则或注册流程，常与其他钩子配合使用。
  • 注意：函数必须返回 $errors 变量，否则可能导致致命错误。

代码示例

function myplugin_check_fields( $errors, $sanitized_user_login, $user_email ) {
    $errors->add( 'demo_error', __( 'ERROR: This is a demo error.', 'my_textdomain' ) );
    return $errors;
}
add_filter( 'registration_errors', 'myplugin_check_fields', 10, 3 );

注意事项

确保函数始终返回 $errors 变量，以避免调用非对象成员函数导致的错误。

📄 原文内容

Filters the errors encountered when a new user is being registered.

Description

The filtered WP_Error object may, for example, contain errors for an invalid or existing username or email address. A WP_Error object should always be returned, but may or may not contain errors.

If any errors are present in $errors, this will abort the user’s registration.

Parameters

$errorsWP_Error
A WP_Error object containing any errors encountered during registration.
$sanitized_user_loginstring
User’s username after it has been sanitized.
$user_emailstring
User’s email.

More Information

This filter can be used to create custom validation rules on user registration. This fires when the form is submitted but before user information is saved to the database.

When used with other hooks, this filter can be used to create custom registration processes.

The form will not create a new user if any errors are returned. Notice: The function must return the variable $errors in any case (even when there is no error in your logic), otherwise the function may cause this problem: Fatal error: Call to a member function get_error_code() on a non-object.

Source

$errors = apply_filters( 'registration_errors', $errors, $sanitized_user_login, $user_email );

View all references View on Trac View on GitHub

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

Handles registering a new user.

Changelog

Version Description
2.1.0 Introduced.

User Contributed Notes

  1. Skip to note 4 content


    Steven Lin


    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 migrated from Codex:

    Returning an Error

    This example shows how to return an error.

    function myplugin_check_fields( $errors, $sanitized_user_login, $user_email ) {

    $errors->add( 'demo_error', __( '<strong>ERROR</strong>: This is a demo error.', 'my_textdomain' ) );
    return $errors;
}

add_filter( 'registration_errors', 'myplugin_check_fields', 10, 3 );

  2. Skip to note 5 content


    Steven Lin


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

    Example migrated from Codex:

    Validating a Custom Field

    Assuming you wanted to validate a postal code field that you have already created using the register_form hook, you might validate the field like so:

    function myplugin_check_fields( $errors, $sanitized_user_login, $user_email ) {

    if ( ! preg_match('/[0-9]{5}/', $_POST['zipcode'] ) ) {
        $errors->add( 'zipcode_error', __( '<strong>ERROR</strong>: Invalid Zip.', 'my_textdomain' ) );
    }

    return $errors;
}

add_filter( 'registration_errors', 'myplugin_check_fields', 10, 3 );

  3. Skip to note 6 content


    Muhammad Arslan


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

    If you want to change the register message here is the documentation.

    add_filter( 'registration_errors', 'wpdocs_registration_errors' );

/**
 * Change the Register Error message when an email is already there
 *
 * @param object $error Default error message.
 * @return void $error Customized error message.
 */
function wpdocs_registration_errors( $error ) {
    if ( $error->get_error_messages( 'email_exists' ) ) {
        $error = new WP_Error( 'email_exists', __( 'Your email is already registered. Thanks!' ) );
    }

    return $error;
}