registration_errors │ filter-hook │ WP 2.1.0

Allows you to add custom registration checks and change error messages on the registration page.

The filter receives a WP_Error object, which may contain errors (the user already exists, the email address is invalid, and so on) or may be empty. In both cases, the WP_Error object must be returned; otherwise, a 500 error occurs.

If WP_Error contains data, user registration is interrupted. This makes it possible to add custom registration checks and stop registration with an error when necessary.

After successful validation, the WP_Error object is empty and looks like this:

WP_Error Object (
	[errors]     => Array()
	[error_data] => Array()
)

This is what WP_Error looks like when registration errors occur, for example, when the username and email address are missing:

WP_Error Object (
	[errors] => Array (
		[empty_username] => Array (
			[0] => <strong>ERROR</strong>: Please enter a username.
		)

		[empty_email] => Array (
			[0] => <strong>ERROR</strong>: Please enter your email address.
		)
	)

	[error_data] => Array()
)

Usage

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

/**
 * Function for `registration_errors` filter-hook.
 * 
 * @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.
 *
 * @return WP_Error
 */
function wp_kama_registration_errors_filter( $errors, $sanitized_user_login, $user_email ){

	// filter...
	return $errors;
}

$errors(WP_Error)

WP_Error object containing registration errors, or an empty object.

$sanitized_user_login(string)

Sanitized username.

$user_email(string)

User's email address.

Examples

#1 A simple registration spam check

Add a checkbox and verify that it was selected. If it was not, display an error:

<?php

add_filter( 'registration_errors', 'add_registration_errors' );
add_action( 'register_form', 'register_form_add_field' );

/**
 * Adds an error if the registration checkbox was not selected.
 *
 * @param WP_Error $errors
 *
 * @return WP_Error
 */
function add_registration_errors( $errors ) {
	if ( filter_input( INPUT_POST, 'i-not-robot' ) !== 'yes' ) {
		$errors->add( 'robot_detected', '<strong>ERROR</strong>: Robots are not welcome here!' );
	}

	return $errors;
}

/**
 * Displays a checkbox in the default registration form.
 *
 * @return void
 */
function register_form_add_field() {
	?>
	<p>
		<label>
			<input type="checkbox" name="i-not-robot" value="yes"> I am human!
		</label>
	</p>
	<br>
	<?php
}