register_new_user()

💡 云策文档标注

概述

register_new_user() 函数用于处理新用户注册，通过 WordPress 登录页面插入新用户到数据库。它验证用户名和邮箱的有效性，生成随机密码，并依赖 wp_create_user() 创建用户，同时提供相关钩子用于自定义验证和注册过程。

关键要点

函数参数：必需参数为 $user_login（用户名）和 $user_email（邮箱地址），返回用户 ID 或 WP_Error 对象。
功能差异：与 wp_create_user() 不同，register_new_user() 不允许多选密码，而是使用 wp_generate_password() 生成随机密码，适合标准注册流程。
验证流程：检查用户名和邮箱的非空性、合法性、唯一性，并应用 filters 如 user_registration_email 和 illegal_user_logins。
钩子支持：提供 register_post 和 registration_errors 钩子，允许开发者在用户创建前后自定义验证和错误处理。
错误处理：注册失败时返回 WP_Error，成功时发送通知邮件并设置用户元数据。

代码示例

$user_login = sanitize_text_field( $_POST['user_login'] );
$user_email = sanitize_email( $_POST['user_email'] );
$user = register_new_user( $user_login, $user_email );
if ( ! is_wp_error( $user ) ) {
	$redirect_to = ! empty( $_POST['redirect_to'] ) ? $_POST['redirect_to'] : 'wp-login.php?checkemail=registered';
	wp_safe_redirect( $redirect_to );
	exit();
}

注意事项

若需指定密码或额外参数，应使用 wp_create_user() 或 wp_insert_user() 替代。
函数内部调用 wp_new_user_notification() 发送密码通知邮件，确保邮件配置正确。
注册失败时，错误信息可通过 WP_Error 对象获取，便于调试和用户反馈。

📄 原文内容

Handles registering a new user.

Parameters

$user_loginstringrequired: User’s username for logging in
$user_emailstringrequired: User’s email address to send password and add

Return

int|WP_Error Either user’s ID or error on failure.

The register_new_user() function inserts a new user into the WordPress database. This function is used when a new user registers through WordPress’ Login Page. It differs from wp_create_user() in that it requires a valid username and email address but doesn’t allow to choose a password, generating a random one using wp_generate_password(). If you want to create a new user with a specific password or with additional parameters, use wp_create_user() or wp_insert_user() instead.

register_new_user() doesn’t handle the user creation itself, it simply checks the submitted username and email validity and generates a random password, relying on wp_create_user() to create the new User. If registration worked it sends a notification email to the user with his password using wp_new_user_notification(). In case of registration failure it returns a WP_Error().

register_new_user() also provides two useful hooks to customize validation rules or user registration process, register_post and registration_errors.

Source

function register_new_user( $user_login, $user_email ) {
	$errors = new WP_Error();

	$sanitized_user_login = sanitize_user( $user_login );
	/**
	 * Filters the email address of a user being registered.
	 *
	 * @since 2.1.0
	 *
	 * @param string $user_email The email address of the new user.
	 */
	$user_email = apply_filters( 'user_registration_email', $user_email );

	// Check the username.
	if ( '' === $sanitized_user_login ) {
		$errors->add( 'empty_username', __( '<strong>Error:</strong> Please enter a username.' ) );
	} elseif ( ! validate_username( $user_login ) ) {
		$errors->add( 'invalid_username', __( '<strong>Error:</strong> This username is invalid because it uses illegal characters. Please enter a valid username.' ) );
		$sanitized_user_login = '';
	} elseif ( username_exists( $sanitized_user_login ) ) {
		$errors->add( 'username_exists', __( '<strong>Error:</strong> This username is already registered. Please choose another one.' ) );
	} else {
		/** This filter is documented in wp-includes/user.php */
		$illegal_user_logins = (array) apply_filters( 'illegal_user_logins', array() );
		if ( in_array( strtolower( $sanitized_user_login ), array_map( 'strtolower', $illegal_user_logins ), true ) ) {
			$errors->add( 'invalid_username', __( '<strong>Error:</strong> Sorry, that username is not allowed.' ) );
		}
	}

	// Check the email address.
	if ( '' === $user_email ) {
		$errors->add( 'empty_email', __( '<strong>Error:</strong> Please type your email address.' ) );
	} elseif ( ! is_email( $user_email ) ) {
		$errors->add( 'invalid_email', __( '<strong>Error:</strong> The email address is not correct.' ) );
		$user_email = '';
	} elseif ( email_exists( $user_email ) ) {
		$errors->add(
			'email_exists',
			sprintf(
				/* translators: %s: Link to the login page. */
				__( '<strong>Error:</strong> This email address is already registered. <a href="%s">Log in</a> with this address or choose another one.' ),
				wp_login_url()
			)
		);
	}

	/**
	 * Fires when submitting registration form data, before the user is created.
	 *
	 * @since 2.1.0
	 *
	 * @param string   $sanitized_user_login The submitted username after being sanitized.
	 * @param string   $user_email           The submitted email.
	 * @param WP_Error $errors               Contains any errors with submitted username and email,
	 *                                       e.g., an empty field, an invalid username or email,
	 *                                       or an existing username or email.
	 */
	do_action( 'register_post', $sanitized_user_login, $user_email, $errors );

	/**
	 * Filters the errors encountered when a new user is being registered.
	 *
	 * 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.
	 *
	 * @since 2.1.0
	 *
	 * @param WP_Error $errors               A WP_Error object containing any errors encountered
	 *                                       during registration.
	 * @param string   $sanitized_user_login User's username after it has been sanitized.
	 * @param string   $user_email           User's email.
	 */
	$errors = apply_filters( 'registration_errors', $errors, $sanitized_user_login, $user_email );

	if ( $errors->has_errors() ) {
		return $errors;
	}

	$user_pass = wp_generate_password( 12, false );
	$user_id   = wp_create_user( $sanitized_user_login, $user_pass, $user_email );
	if ( ! $user_id || is_wp_error( $user_id ) ) {
		$errors->add(
			'registerfail',
			sprintf(
				/* translators: %s: Admin email address. */
				__( '<strong>Error:</strong> Could not register you… please contact the <a href="mailto:%s">site admin</a>!' ),
				get_option( 'admin_email' )
			)
		);
		return $errors;
	}

	update_user_meta( $user_id, 'default_password_nag', true ); // Set up the password change nag.

	if ( ! empty( $_COOKIE['wp_lang'] ) ) {
		$wp_lang = sanitize_text_field( $_COOKIE['wp_lang'] );
		if ( in_array( $wp_lang, get_available_languages(), true ) ) {
			update_user_meta( $user_id, 'locale', $wp_lang ); // Set user locale if defined on registration.
		}
	}

	/**
	 * Fires after a new user registration has been recorded.
	 *
	 * @since 4.4.0
	 *
	 * @param int $user_id ID of the newly registered user.
	 */
	do_action( 'register_new_user', $user_id );

	return $user_id;
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘illegal_user_logins’, array $usernames ): Filters the list of disallowed usernames.
do_action( ‘register_new_user’, int $user_id ): Fires after a new user registration has been recorded.
do_action( ‘register_post’, string $sanitized_user_login, string $user_email, WP_Error $errors ): Fires when submitting registration form data, before the user is created.
apply_filters( ‘registration_errors’, WP_Error $errors, string $sanitized_user_login, string $user_email ): Filters the errors encountered when a new user is being registered.
apply_filters( ‘user_registration_email’, string $user_email ): Filters the email address of a user being registered.

Uses	Description
get_available_languages()`wp-includes/l10n.php`	Gets all available languages based on the presence of .mo and .l10n.php files in a given directory.
is_email()`wp-includes/formatting.php`	Verifies that an email is valid.
sanitize_user()`wp-includes/formatting.php`	Sanitizes a username, stripping out unsafe characters.
wp_generate_password()`wp-includes/pluggable.php`	Generates a random password drawn from the defined set of characters.
wp_login_url()`wp-includes/general-template.php`	Retrieves the login URL.
wp_create_user()`wp-includes/user.php`	Provides a simpler way of inserting a user into the database.
validate_username()`wp-includes/user.php`	Checks whether a username is valid.
username_exists()`wp-includes/user.php`	Determines whether the given username exists.
email_exists()`wp-includes/user.php`	Determines whether the given email exists.
update_user_meta()`wp-includes/user.php`	Updates user meta field based on user ID.
__()`wp-includes/l10n.php`	Retrieves the translation of $text.
sanitize_text_field()`wp-includes/formatting.php`	Sanitizes a string from user input or from the database.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.
do_action()`wp-includes/plugin.php`	Calls the callback functions that have been added to an action hook.
get_option()`wp-includes/option.php`	Retrieves an option value based on an option name.
is_wp_error()`wp-includes/load.php`	Checks whether the given variable is a WordPress Error.
WP_Error::__construct()`wp-includes/class-wp-error.php`	Initializes the error.

Show 12 more Show less

Changelog

Version	Description
2.5.0	Introduced.

User Contributed Notes

Skip to note 2 content

Codex

11 years ago

Example
As used in wp-login.php:

$user_login = sanitize_text_field( $_POST['user_login'] );
$user_email = sanitize_email( $_POST['user_email'] );
$user = register_new_user( $user_login, $user_email );
if ( ! is_wp_error( $user ) ) {
	$redirect_to = ! empty( $_POST['redirect_to'] ) ? $_POST['redirect_to'] : 'wp-login.php?checkemail=registered';
	wp_safe_redirect( $redirect_to );
	exit();
}

云策 WordPress 开发者社区

函数文档