Understanding what happens during user login

WP-Members’s login process incorporates a number of core WP functions, actions, and filters in order to provide as seamless an integration with other general WP plugins as possible. A lot has to happen to sign in a user, whether using WordPress alone, or along with WP-Members, so it can be confusing when things don’t seem to work correctly. This article breaks down a number of the processes that occur during this process to help you figure out where to look when things go wrong.

First, before the user ever logs in, we have to consider the login form. This article is only focusing on the WP-Members login form, so if the issue is in the native WP form, that’s separate topic.

The login form

The WP-Members login form will include a parameter for redirect: $redirect_to. This is consistent with the native WP argument for integration. This value will always exist in the form’s hidden fields as “redirect_to”.

This value is set automatically when the form is generated. How that is handled is a topic in itself, but the general priority is as follows, from lowest to highest priority:

1. If no redirect is given, the form will post to itself. If the form is being displayed on a restricted page in place of blocked content, then the redirect value will be that same page. Likewise, if the form is displayed by shortcode, it posts to whatever that page is.
2. If the form is the [wpmem_form login] form, a “redirect_to” attribute can be set in the shortcode. This will override the default, but can be overridden by a redirect_to query argument.
3. ?redirect_to= as a URL query arg. This value is given priority over any other values. If it exists, the form’s redirect_to value will be set to this value.

What happens on form submit?

Once the user clicks the form submit button in the login form, validation begins. This runs the WP-Members login function. You can see what this function does in login() function found in the class-wp-members-user.php file. The function’s very first order of business is to run wp_signon():

wp_signon()

The very first thing that happens is that WP’s native wp_signon() is triggered. This begins the process of validating the user. This triggers a number of actions, filters, and functions.

1. secure_signon_cookie filter
2. authenticate filter
3. wp_authenticate() function
   • authenticate filter (a 2nd time)
   • wp_login_failed action (if authentication has failed at this point)
4. An error is returned from wp_signon() at this point if an error exists (this returns to $wpmem->user->login())
5. wp_set_auth_cookie() function
   • auth_cookie_expiration filter
   • secure_auth_cookie filter
   • secure_logged_in_cookie filter
   • Session created with WP_Session_Token
   • wp_generate_auth_cookie() for $scheme
   • wp_generate_auth_cookie() for “logged_in”
   • set_auth_cookie action
   • set_logged_in_cookie action
   • send_auth_cookies filter (can prevent setting of cookie if false)
   • setcookie() sets several cookies – plugins, admin, logged_in
6. If an activation key exists for the user, it is cleared here
7. wp_login action
8. Returns the user object (this returns to $wpmem->user->login())

Back to the WP-Members login() function

If wp_signon() did not trigger an action that exited processing, at this point it has either returned an error object or the user object.

• wpmem_after_wp_signon filter – this gives a chance to look at (and thus, change) the returned value from wp_signon() before we continue.

Does an error exist?

At this point, we check to see if we have a login error. If so, the error is returned and login is halted. If we have a valid user object, we continue.

Redirect

If we are continuing, we need to check where to redirect the user. (That is picked up from the redirect_to field in the form. It is picked up from the $_POST array. Note: the form action is post. If there was a query arg ($_GET), that affects what the form builder puts in the form’s redirect_to hidden input – the $_GET value is not what is picked up in form processing.)

The process here gets the posted redirect_to value and then runs two filters before redirecting this user:

• login_redirect – the native WP redirect filter
• wpmem_login_redirect – WP-Members’s redirect filter

So, we have a default redirect value that was set in the form (see the first section above). That’s where the user will go upon login success. That value can be changed by the login_redirect filter, which is a native WP filter and can be used by any plugin. Then, that value can be further changed by wpmem_login_redirect, which only runs on the WP-Members form.

Summary

To summarize, the user is authenticated by a core WP process, wp_signon(). That function determines if the user has given valid data, such as username and password. If the user passes authentication, WP sets the auth cookies needed to maintain login state and returns a valid user to the WP-Members login function, otherwise it returns the login error.

If wp_signon() returned an error, WP-Members returns that login error. Otherwise, at that point, the only thing left to do is to return to the page identified as the redirect_to value. This will first be whatever the redirect_to value is in the login form. It can be changed by WP’s login_redirect filter, and then further changed by WP-Members using wpmem_login_redirect.