Refactor email activation flow in Ultimate Member.

Improved readability and clarity of the email activation process by updating comments and restructuring conditional checks. Added hooks and filters for better customization, including redirect URL filtering. Replaced `wp_redirect` with `um_safe_redirect` for safer redirection handling.

includes/core/class-permalinks.php

@@ -134,41 +134,38 @@ if ( ! class_exists( 'um\core\Permalinks' ) ) {
 					exit;
 				}
 
-				// approve.
-				um_fetch_user( $user_id );
+				// Activate account link is valid. Can be approved below.
+
+				um_fetch_user( $user_id ); // @todo maybe don't need to fetch.
 				UM()->common()->users()->approve( $user_id, true );
 
 				$user_role      = UM()->roles()->get_priority_user_role( $user_id );
 				$user_role_data = UM()->roles()->role_data( $user_role );
 
-				// log in automatically
+				// Log in automatically after activation.
 				$login = ! empty( $user_role_data['login_email_activate'] ); // Role setting "Login user after validating the activation link?"
-				if ( ! is_user_logged_in() && $login ) {
+				if ( $login && ! is_user_logged_in() ) {
 					UM()->user()->auto_login( $user_id );
 				}
 
 				/**
-				 * UM hook
+				 * Fires on user activation after visit link for email confirmation.
 				 *
-				 * @type action
-				 * @title um_after_email_confirmation
-				 * @description Action on user activation
-				 * @input_vars
-				 * [{"var":"$user_id","type":"int","desc":"User ID"}]
-				 * @change_log
-				 * ["Since: 2.0"]
-				 * @usage add_action( 'um_after_email_confirmation', 'function_name', 10, 1 );
-				 * @example
-				 * <?php
-				 * add_action( 'um_after_email_confirmation', 'my_after_email_confirmation', 10, 1 );
+				 * @hook um_after_email_confirmation
+				 *
+				 * @param {int} $user_id The user ID.
+				 *
+				 * @since 2.0
+				 *
+				 * @example <caption>Doing some code after email confirmation and approved $user_id.</caption>
 				 * function my_after_email_confirmation( $user_id ) {
 				 *     // your code here
 				 * }
-				 * ?>
+				 * add_filter( 'um_after_email_confirmation', 'my_after_email_confirmation' );
 				 */
 				do_action( 'um_after_email_confirmation', $user_id );
 
-				// redirect.
+				// Prepare redirect link.
 				$set_password_required = get_user_meta( $user_id, 'um_set_password_required', true );
 				if ( empty( $set_password_required ) ) {
 					// Role setting "URL redirect after email activation".
@@ -178,9 +175,29 @@ if ( ! class_exists( 'um\core\Permalinks' ) ) {
 					um_fetch_user( $user_id );
 					$redirect = um_user( 'password_reset_link' );
 				}
+				/**
+				 * Filter to change the redirect URL after email confirmation.
+				 *
+				 * @hook um_after_email_confirmation_redirect
+				 *
+				 * @param {string} $redirect The redirect URL.
+				 * @param {int}    $user_id  The user ID.
+				 * @param {bool}   $login    Auto login has been applied and user currently is logged in.
+				 *
+				 * @since 2.0
+				 *
+				 * @example <caption>Change redirect after confirmation only for the user with ID=99.</caption>
+				 * function my_after_email_confirmation_redirect( $redirect, $user_id, $login ) {
+				 *     // your code here
+				 *     if ( $user_id === 99 ) {
+				 *         $redirect = 'custom_url';
+				 *     }
+				 *     return $redirect;
+				 * }
+				 * add_filter( 'um_after_email_confirmation_redirect', 'my_after_email_confirmation_redirect', 10, 3 );
+				 */
 				$redirect = apply_filters( 'um_after_email_confirmation_redirect', $redirect, $user_id, $login );
-
-				exit( wp_redirect( $redirect ) );
+				um_safe_redirect( $redirect );
 			}
 		}