A visual guide to WordPress user registration hooks

There are many different WordPress hooks that are called during the user creation and registration process and it’s very important to understand how everything works together in order to choose the most appropriate hooks for your task. In this article, we are going to deep dive into WordPress user registration hooks. We are going to show you some visual representations to help you understand which actions and filters are called during user registration, as well as the sequence in which they are called.

What Are WordPress Hooks?

WordPress hooks are functions that can be applied to an action or a filter in order to customize code or change default WordPress behavior. Custom hooks can be created by developers to allow for even more flexibility and customization on a WordPress site. Hooks can be applied to almost every aspect of WordPress, and are one of the most powerful tools in a developer’s toolkit.

WordPress Actions and Filters

WordPress provides many different hooks that allow us to customize most of its functionality. There are two types of hooks – actions and filters.

Actions are designed to allow you to run custom functionality at a specific point of the code execution. Filters, on the other hand, allow you to modify specific values.

The hooks fired during user registration depend on the method of registration. WordPress by default provides two methods of user registration – by using the registration form and via the admin dashboard. In this article, we are going to look into the hook cycle for both of these methods, as they are very different from each other. However, please keep in mind that if you are using a third party plugin for your site’s user registration, the hooks used there might be different as well.

User registration hooks fired when using the user registration form

The user registration form is available when the “Anyone can register” option is enabled under Settings -> General.

 

The following graphic illustrates the sequence of the main WordPress hooks fired when using the default user signup form. We are going to focus mainly on the registration-related hooks, fired between the form submission and the page redirection after a successful registration.

Please note that some of these hooks are not limited to the registration form. For example, the pre_user_login and wp_pre_insert_user_data hooks are called every time the wp_insert_user()  function is called. This function can be called not only from the registration form but also from the admin dashboard’s new user interface or from other 3rd party plugins’ elements.

Now let’s go through each of these hooks.

user_registration_email filter

The user_registration_email  filter allows you to modify the email submitted through the form. Although this is a filter, the WordPress codex also suggests that if you need to modify any of the $_POST data submitted through this form, you could use this filter to do that. That’s because this is one of the first hooks that is fired after the form submission. Also, this filter is directly followed by the validation of the form inputs, so it’s best to apply any data modifications before the validations. Otherwise, if you decide to modify the user data in a later hook and skip the default WordPress validation, this might lead to some unexpected errors.

register_post action

The register_post action is fired just after the WordPress validation of the user signup form fields but before the registration_errors filter. You should avoid using this action for custom validations – use the registration_errors filter instead.

registration_errors filter

This filter allows you to perform custom validations upon registration, by directly modifying the errors object. User creation will proceed only when the errors object is empty. Therefore, if you add any errors to the error object, the user registration process will be terminated and your error messages will be displayed to the user. You can learn more about how to use this filter on the WordPress registration_errors codex page.

pre_user_login & pre_user_email filters

The pre_user_login filter allows you to modify the username of a user before it is saved in the database. Similarly, the pre_user_email filter allows you to modify the email. Along with these filters, there are several other similar filters fired that you can use to change the user data:

• pre_user_nicename – allows filtering the user’s nicename
• pre_user_url – allows filtering the user’s URL
• pre_user_nickname – allows filtering the user’s nickname
• pre_user_first_name – allows filtering the user’s first name
• pre_user_last_name – allows filtering the user’s last name
• pre_user_display_name – allows filtering the user’s display name
• pre_user_description – allows filtering the user’s description

Please note that these filters might be also fired when updating an existing user.

wp_pre_insert_user_data

The wp_pre_insert_user_data filter allows you to filter the user data before the user is saved in the database. This filter is not specific to the registration form and might be also fired when updating a user. You can read more about how to use this method here.

user_register & register_new_user actions

These two actions are very similar to each other. They are both called immediately after the user record is created in the database and both pass the user ID as an argument. The main difference between the user_register and the register_new_user action is that register_new_user is fired only from the user registration form, while user_register can be fired anytime a new user is created, regardless of the form used.

WordPress registration hooks fired from the Add New User profile page

As we discussed earlier, the WordPress user registration hooks that are fired from the Add New User profile page of the WordPress admin dashboard are different from the ones fired from the User Registration form. Therefore, if you need to customize your user registration process, you’ll need to understand how both elements work so you can pick the right WordPress hooks to use.

 

Now let’s take a look at which actions and filters are called when creating a new user from this screen:

It’s important to reiterate that not all hooks are specific to this screen and some hooks fire whenever a new user is created.

Something you might have observed is that there is no hook activated at the start of the request. Once the form is submitted, data sanitization and some of the validation code executes before any hooks are run.

check_passwords action

The check_passwords action is called during the validation process. WordPress first validates the presence of the username and nickname fields, then it calls the check_passwords action, and after that it processes the rest of the validation. This action is called check_passwords because it is executed right before checking if the two passwords match. This action passes the two passwords as arguments.

You may have noticed that the Add User form has only one password field and wonder where the second one comes from. Well, the password confirmation field exists hidden in the form when JavaScript is enabled. In this case, it will be automatically populated with the same value entered from the main password field and this value would be sent in the request.

user_profile_update_errors action

The user_profile_update_errors  action is called just after the validation. This WordPress profile page hook is the action that you can use to introduce custom validation rules. The action passes an errors object as an argument. If any errors are present in the errors object, the user creation will be aborted. This action is called during both user creation and user updates. Therefore, if you need to hook only to user creation, you can use the $update  argument that the action passes. This argument will be set to false  when a new user is being created. For more information and an usage example, head over to the user_profile_update_errors documentation.

User data filters

Similarly to the user registration form, there are several filters that you can use to modify the user data before it is stored in the database. These are the filters that are called for each field separately, such as the pre_user_login and pre_user_email filter. Then they are followed by the wp_pre_insert_user_data filter that passes all the user data as an argument. We have discussed these hooks in more detail earlier in this article.

user_register & edit_user_created_user actions

The user_register and edit_user_created_user actions are both called after the user record has been created in the database. These two hooks are very similar. The main difference is that edit_user_created_user is called only from the Add New User screen in the dashboard, while user_register is called every time a new user is created by using the wp_insert_user()  function.

 

Conclusion

A WordPress hook is a PHP function that is executed at specific times during the life of a page or post request or any other process on your WordPress site. These functions can be created by a theme or plugin developer to perform specific tasks. In this article we went through all the main WordPress hooks that are fired during the WordPress user registration process. We learned that WordPress provides various filters and actions that can allow us to customize the user registration process in many different ways.

You might be asking yourself “which hook should I use?”. Well, that really depends. As we saw earlier, there are different WordPress hooks that are called depending on the registration form used. If you need to customize the overall user creation process, regardless of the form used, you should probably look into using the hooks that are called every time a user is created in the database. For example, these are the wp_pre_insert_user_data filter and the user_register action. If however you need to customize the registration process specifically in one of the forms, you could use the form specific hooks. For example, that would be register_new_user for the user registration form and edit_user_created_user for the Add New User form. Also, if you are using a 3rd party plugin for user registration, you should keep in mind that the hooks fired there might differ from the default ones.

We hope that you have found this article useful, and see you again next time!