Merge pull request 'Invite links: page selector + auto-redirect for stray tokens' (#19) from fix/invite-registration-page-selector into main

Reviewed-on: #19

docs/features/account-registration.md

@@ -41,12 +41,20 @@ recorded in `us_policy_acceptances` with `registration_type = account` and
 
 ## Admin Interface
 **Invites** in wp-admin (`manage_students`, studio admin only):
+- Select the **registration page** (the page hosting `[us_student_register]`), stored in the `us_registration_page_id` option; invitation links point there (falling back to the home page if unset)
 - Invite an email (creates a pending invite + link)
 - List pending invites; revoke an invite
 
 ## Frontend Shortcode
 - `[us_student_register]` — the registration page. Shows the form for a valid pending invite; otherwise shows an "by invitation only" message (in `invite` mode).
 
+## Token Redirect
+A `template_redirect` handler (`RegistrationPage::maybeRedirectToRegistrationPage()`)
+sends any front-end request carrying a `us_invite` token to the configured
+registration page (preserving the token), unless it is already on that page. This
+covers invitation links generated/shared before a registration page was selected.
+No-op when no registration page is set.
+
 ## Capabilities
 - `manage_students` — manage invites (studio admin; administrators inherit it via the `user_has_cap` filter). Added to `RoleManager::STUDIO_ADMIN_CAPS`.
 

src/Auth/RegistrationController.php

@@ -5,6 +5,11 @@ namespace Unsupervised\Schedular\Auth;
 
 class RegistrationController {
 
+	/**
+	 * Option storing the page ID that hosts the [us_student_register] shortcode.
+	 */
+	public const OPTION_PAGE = 'us_registration_page_id';
+
 	public function __construct( private InviteRepository $invites ) {}
 
 	public function renderPage(): void {
@@ -16,7 +21,9 @@ class RegistrationController {
 			$this->handleFormAction();
 		}
 
-		$pendingInvites = $this->invites->findPending();
+		$pendingInvites      = $this->invites->findPending();
+		$registrationPageId  = (int) get_option( self::OPTION_PAGE, 0 );
+		$registrationPageUrl = $registrationPageId > 0 ? (string) get_permalink( $registrationPageId ) : '';
 
 		include USC_PLUGIN_DIR . 'templates/admin/invites.php';
 	}
@@ -26,6 +33,10 @@ class RegistrationController {
 		// phpcs:disable WordPress.Security.NonceVerification.Missing
 		$action = sanitize_key( wp_unslash( $_POST['usc_action'] ?? '' ) );
 
+		if ( 'set_page' === $action ) {
+			update_option( self::OPTION_PAGE, absint( $_POST['registration_page_id'] ?? 0 ) );
+		}
+
 		if ( 'invite' === $action ) {
 			$email = sanitize_email( wp_unslash( $_POST['email'] ?? '' ) );
 

src/Auth/RegistrationPage.php

@@ -52,6 +52,31 @@ class RegistrationPage {
 		return (string) ob_get_clean();
 	}
 
+	/**
+	 * Redirect to the configured registration page when an invite token lands
+	 * elsewhere (e.g. a link generated before the page was selected). Hooked on
+	 * `template_redirect`.
+	 */
+	public function maybeRedirectToRegistrationPage(): void {
+		if ( is_admin() ) {
+			return;
+		}
+
+		// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only token used only to build the redirect target.
+		$token = sanitize_text_field( wp_unslash( $_GET['us_invite'] ?? '' ) );
+		if ( '' === $token ) {
+			return;
+		}
+
+		$pageId = (int) get_option( RegistrationController::OPTION_PAGE, 0 );
+		if ( $pageId <= 0 || is_page( $pageId ) ) {
+			return;
+		}
+
+		wp_safe_redirect( add_query_arg( 'us_invite', rawurlencode( $token ), (string) get_permalink( $pageId ) ) );
+		exit;
+	}
+
 	/**
 	 * Process the submitted registration. Returns true on success or an error
 	 * message string on failure.

src/ShortcodeRegistrar.php

@@ -32,6 +32,7 @@ class ShortcodeRegistrar {
 		add_shortcode( 'us_booking', [ $this->bookingPage, 'render' ] );
 		add_shortcode( 'us_student_login', [ $this->loginPage, 'render' ] );
 		add_shortcode( 'us_student_register', [ $this->registrationPage, 'render' ] );
+		add_action( 'template_redirect', [ $this->registrationPage, 'maybeRedirectToRegistrationPage' ] );
 		add_action( 'wp_enqueue_scripts', [ $this, 'enqueueAssets' ] );
 	}
 

templates/admin/invites.php

@@ -5,12 +5,46 @@ if (! defined('ABSPATH')) {
     exit;
 }
 
-/** @var list<\Unsupervised\Schedular\Auth\Invite> $pendingInvites */
+/**
+ * @var list<\Unsupervised\Schedular\Auth\Invite> $pendingInvites
+ * @var int    $registrationPageId
+ * @var string $registrationPageUrl
+ */
 ?>
 <div class="wrap">
     <h1><?php esc_html_e('Invites', 'unsupervised-schedular'); ?></h1>
     <p class="description"><?php esc_html_e('Invite a student by email, then send them the registration link below. They complete signup and accept any required policies through the [us_student_register] page.', 'unsupervised-schedular'); ?></p>
 
+    <h2><?php esc_html_e('Registration Page', 'unsupervised-schedular'); ?></h2>
+    <form method="post">
+        <?php wp_nonce_field('usc_invite_action'); ?>
+        <input type="hidden" name="usc_action" value="set_page">
+        <table class="form-table">
+            <tr>
+                <th><label for="registration_page_id"><?php esc_html_e('Page with the registration form', 'unsupervised-schedular'); ?></label></th>
+                <td>
+                    <?php
+                    wp_dropdown_pages(
+                        [
+                            'name'              => 'registration_page_id',
+                            'id'                => 'registration_page_id',
+                            'selected'          => $registrationPageId,
+                            'show_option_none'  => esc_html__('— Select a page —', 'unsupervised-schedular'),
+                            'option_none_value' => '0',
+                        ]
+                    );
+                    ?>
+                    <p class="description"><?php esc_html_e('Choose the page that contains the [us_student_register] shortcode. Invitation links point here.', 'unsupervised-schedular'); ?></p>
+                </td>
+            </tr>
+        </table>
+        <?php submit_button(esc_html__('Save Page', 'unsupervised-schedular'), 'secondary'); ?>
+    </form>
+
+    <?php if ($registrationPageUrl === '') : ?>
+        <div class="notice notice-warning inline"><p><?php esc_html_e('No registration page is set yet — invitation links will fall back to the site home page. Select a page above.', 'unsupervised-schedular'); ?></p></div>
+    <?php endif; ?>
+
     <h2><?php esc_html_e('Invite a Student', 'unsupervised-schedular'); ?></h2>
     <form method="post">
         <?php wp_nonce_field('usc_invite_action'); ?>
@@ -21,7 +55,7 @@ if (! defined('ABSPATH')) {
                 <td><input type="email" name="email" id="email" class="regular-text" required></td>
             </tr>
         </table>
-        <?php submit_button(esc_html__('Send Invite', 'unsupervised-schedular')); ?>
+        <?php submit_button(esc_html__('Generate Invitation Link', 'unsupervised-schedular')); ?>
     </form>
 
     <h2><?php esc_html_e('Pending Invites', 'unsupervised-schedular'); ?></h2>
@@ -38,13 +72,13 @@ if (! defined('ABSPATH')) {
                 </tr>
             </thead>
             <tbody>
+                <?php $linkBase = $registrationPageUrl !== '' ? $registrationPageUrl : home_url('/'); ?>
                 <?php foreach ($pendingInvites as $invite) : ?>
-                    <?php $link = esc_url(add_query_arg('us_invite', $invite->token, home_url('/'))); ?>
+                    <?php $link = esc_url(add_query_arg('us_invite', $invite->token, $linkBase)); ?>
                     <tr>
                         <td><?php echo esc_html($invite->email); ?></td>
                         <td>
                             <input type="text" class="large-text code" readonly value="<?php echo esc_attr($link); ?>" onclick="this.select()">
-                            <span class="description"><?php esc_html_e('Point this token (?us_invite=…) at the page containing the registration shortcode.', 'unsupervised-schedular'); ?></span>
                         </td>
                         <td>
                             <form method="post" style="display:inline;">