Document redirectAfterLogin() usage

Author: dereuromark

docs/en/authentication-component.md

@@ -121,3 +121,34 @@ option or by calling `disableIdentityCheck` from the controller's `beforeFilter(
 ``` php
 $this->Authentication->disableIdentityCheck();
 ```
+
+## Redirecting after login
+
+For the common post-login redirect flow, use `redirectAfterLogin()`:
+
+``` php
+public function login(): ?\Cake\Http\Response
+{
+    $result = $this->Authentication->getResult();
+
+    if ($result && $result->isValid()) {
+        return $this->Authentication->redirectAfterLogin('/home');
+    }
+
+    return null;
+}
+```
+
+This uses the plugin's validated login redirect target from the current
+request when available and falls back to the default you provide.
+
+If you need to inspect the validated target before redirecting, use
+`getLoginRedirect()` instead:
+
+``` php
+$target = $this->Authentication->getLoginRedirect('/home');
+return $this->redirect($target);
+```
+
+Avoid reading raw `redirect` query string parameters and passing them directly
+to the controller's `redirect()` method.

docs/en/authenticators.md

@@ -581,8 +581,8 @@ $service->setConfig([
 ]);
 ```
 
-Then in your controller's login method you can use `getLoginRedirect()` to get
-the redirect target safely from the query string parameter:
+Then in your controller's login method you can use
+`redirectAfterLogin()` for the common safe post-login redirect flow:
 
 ``` php
 public function login(): ?\Cake\Http\Response
@@ -591,19 +591,21 @@ public function login(): ?\Cake\Http\Response
 
     // Regardless of POST or GET, redirect if user is logged in
     if ($result->isValid()) {
-        // Use the redirect parameter if present.
-        $target = $this->Authentication->getLoginRedirect();
-        if (!$target) {
-            $target = ['controller' => 'Pages', 'action' => 'display', 'home'];
-        }
-
-        return $this->redirect($target);
+        return $this->Authentication->redirectAfterLogin([
+            'controller' => 'Pages',
+            'action' => 'display',
+            'home',
+        ]);
     }
 
     return null;
 }
 ```
 
+If you need to inspect the validated target before redirecting, you can still
+use `getLoginRedirect()` directly and handle the response yourself. Avoid
+passing raw query string parameters to the controller's `redirect()` method.
+
 ## Having Multiple Authentication Flows
 
 In an application that provides both an API and a web interface

docs/en/index.md

@@ -173,9 +173,7 @@ public function login(): ?\Cake\Http\Response
     $result = $this->Authentication->getResult();
     // If the user is logged in send them away.
     if ($result && $result->isValid()) {
-        $target = $this->Authentication->getLoginRedirect() ?? '/home';
-
-        return $this->redirect($target);
+        return $this->Authentication->redirectAfterLogin('/home');
     }
     if ($this->request->is('post')) {
         $this->Flash->error('Invalid username or password');

docs/en/migration-from-the-authcomponent.md

@@ -288,8 +288,8 @@ $service->setConfig([
 ]);
 ```
 
-Then in your controller's login method you can use `getLoginRedirect()` to get
-the redirect target safely from the query string parameter:
+Then in your controller's login method you can use
+`redirectAfterLogin()` for the common safe post-login redirect flow:
 
 ``` php
 public function login(): ?\Cake\Http\Response
@@ -298,19 +298,20 @@ public function login(): ?\Cake\Http\Response
 
     // Regardless of POST or GET, redirect if user is logged in
     if ($result->isValid()) {
-        // Use the redirect parameter if present.
-        $target = $this->Authentication->getLoginRedirect();
-        if (!$target) {
-            $target = ['controller' => 'Pages', 'action' => 'display', 'home'];
-        }
-
-        return $this->redirect($target);
+        return $this->Authentication->redirectAfterLogin([
+            'controller' => 'Pages',
+            'action' => 'display',
+            'home',
+        ]);
     }
 
     return null;
 }
 ```
 
+If you need to inspect the validated target before redirecting, you can still
+use `getLoginRedirect()` directly and then call `redirect()` yourself.
+
 ## Migrating Hashing Upgrade Logic
 
 If your application uses `AuthComponent`’s hash upgrade