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.
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 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 this 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 new user interface or from other 3rd party plugins’ elements.
Now let’s go through each of these hooks.
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.
The register_post action is fired just after the WordPress validation of the form fields, but before the registration_errors filter. You should avoid using this action for custom validations – use the registration_errors filter instead.
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.
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 page
As we discussed earlier, the WordPress user registration hooks that are fired from the Add New User page of the 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:
Here it’s important to mention again that not all of the hooks are specific to this screen and some of them are fired whenever a new user is created.
One thing that you might have noticed is that there isn’t a hook that is called at the very beginning of the request. Once the form is submitted, the data sanitization and part of the validation code run before any hooks are fired.
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.
The user_profile_update_errors action is called just after the validation. This 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.
In this article we went trough 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!