Fix documentation issues (3rd pass)

- Add return types to all controller action examples (login, logout, etc.)
- Fix "Let's" grammar (was "Lets")
- Fix `stopImpersonation()` typo -> `stopImpersonating()`
- Replace deprecated `TableRegistry::getTableLocator()->get()` with `fetchTable()`
- Fix indentation inconsistency in testing examples
- Add missing redirect return in revertIdentity() example
- Use `fetchTable()` instead of `$this->Users` property access
- Use `saveOrFail()` instead of `save()` for better error handling
- Use `'plugin' => false` instead of `'plugin' => null` for consistency
- Add trailing commas in arrays

Author: dereuromark

docs/en/authenticators.md

@@ -196,7 +196,7 @@ In your `UsersController`:
 ``` php
 use Firebase\JWT\JWT;
 
-public function login()
+public function login(): void
 {
     $result = $this->Authentication->getResult();
     if ($result->isValid()) {
@@ -585,7 +585,7 @@ Then in your controller's login method you can use `getLoginRedirect()` to get
 the redirect target safely from the query string parameter:
 
 ``` php
-public function login()
+public function login(): ?\Cake\Http\Response
 {
     $result = $this->Authentication->getResult();
 
@@ -596,8 +596,11 @@ public function login()
         if (!$target) {
             $target = ['controller' => 'Pages', 'action' => 'display', 'home'];
         }
+
         return $this->redirect($target);
     }
+
+    return null;
 }
 ```
 

docs/en/impersonation.md

@@ -12,7 +12,7 @@ user from your application's database:
 
 ``` php
 // In a controller
-public function impersonate()
+public function impersonate(): \Cake\Http\Response
 {
     $this->request->allowMethod(['POST']);
 
@@ -25,9 +25,9 @@ public function impersonate()
     }
 
     // Fetch the user we want to impersonate.
-    $targetUser = $this->Users->findById(
-        $this->request->getData('user_id')
-    )->firstOrFail();
+    $targetUser = $this->fetchTable('Users')
+        ->findById($this->request->getData('user_id'))
+        ->firstOrFail();
 
     // Enable impersonation.
     $this->Authentication->impersonate($targetUser);
@@ -46,7 +46,7 @@ back to your previous identity using `AuthenticationComponent`:
 
 ``` php
 // In a controller
-public function revertIdentity()
+public function revertIdentity(): \Cake\Http\Response
 {
     $this->request->allowMethod(['POST']);
 
@@ -55,6 +55,8 @@ public function revertIdentity()
         throw new NotFoundException();
     }
     $this->Authentication->stopImpersonating();
+
+    return $this->redirect($this->referer());
 }
 ```
 
@@ -64,4 +66,4 @@ There are a few limitations to impersonation.
 
 1.  Your application must be using the `Session` authenticator.
 2.  You cannot impersonate another user while impersonation is active. Instead
-    you must `stopImpersonation()` and then start it again.
+    you must `stopImpersonating()` and then start it again.

docs/en/index.md

@@ -109,7 +109,7 @@ public function getAuthenticationService(ServerRequestInterface $request): Authe
         'fields' => $fields,
         'loginUrl' => Router::url([
             'prefix' => false,
-            'plugin' => null,
+            'plugin' => false,
             'controller' => 'Users',
             'action' => 'login',
         ]),
@@ -168,17 +168,20 @@ like:
 
 ``` php
 // in src/Controller/UsersController.php
-public function login()
+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);
     }
     if ($this->request->is('post')) {
         $this->Flash->error('Invalid username or password');
     }
+
+    return null;
 }
 ```
 
@@ -188,7 +191,7 @@ unauthenticated users are able to access it:
 
 ``` php
 // in src/Controller/UsersController.php
-public function beforeFilter(\Cake\Event\EventInterface $event)
+public function beforeFilter(\Cake\Event\EventInterface $event): void
 {
     parent::beforeFilter($event);
 
@@ -216,9 +219,10 @@ Then add a simple logout action:
 
 ``` php
 // in src/Controller/UsersController.php
-public function logout()
+public function logout(): \Cake\Http\Response
 {
     $this->Authentication->logout();
+
     return $this->redirect(['controller' => 'Users', 'action' => 'login']);
 }
 ```

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

@@ -184,20 +184,23 @@ upon a successful login, change your login action to check the new
 identity results:
 
 ``` php
-public function login()
+public function login(): ?\Cake\Http\Response
 {
     $result = $this->Authentication->getResult();
 
-    // regardless of POST or GET, redirect if user is logged in
+    // Regardless of POST or GET, redirect if user is logged in
     if ($result->isValid()) {
         $target = $this->Authentication->getLoginRedirect();
+
         return $this->redirect($target);
     }
 
-    // display error if user submitted and authentication failed
+    // Display error if user submitted and authentication failed
     if ($this->request->is('post')) {
         $this->Flash->error('Invalid username or password');
     }
+
+    return null;
 }
 ```
 
@@ -289,7 +292,7 @@ Then in your controller's login method you can use `getLoginRedirect()` to get
 the redirect target safely from the query string parameter:
 
 ``` php
-public function login()
+public function login(): ?\Cake\Http\Response
 {
     $result = $this->Authentication->getResult();
 
@@ -300,8 +303,11 @@ public function login()
         if (!$target) {
             $target = ['controller' => 'Pages', 'action' => 'display', 'home'];
         }
+
         return $this->redirect($target);
     }
+
+    return null;
 }
 ```
 
@@ -312,29 +318,33 @@ functionality. You can replicate that logic with this plugin by
 leveraging the `AuthenticationService`:
 
 ``` php
-public function login()
+public function login(): ?\Cake\Http\Response
 {
     $result = $this->Authentication->getResult();
 
-    // regardless of POST or GET, redirect if user is logged in
+    // Regardless of POST or GET, redirect if user is logged in
     if ($result->isValid()) {
         $authService = $this->Authentication->getAuthenticationService();
 
         // Get the identifier that was used for authentication.
         $identifier = $authService->getIdentificationProvider();
         if ($identifier !== null && $identifier->needsPasswordRehash()) {
             // Rehash happens on save.
-            $user = $this->Users->get($this->Authentication->getIdentityData('id'));
+            $user = $this->fetchTable('Users')->get(
+                $this->Authentication->getIdentityData('id')
+            );
             $user->password = $this->request->getData('password');
-            $this->Users->save($user);
+            $this->fetchTable('Users')->saveOrFail($user);
         }
 
         // Redirect to a logged in page
         return $this->redirect([
             'controller' => 'Pages',
             'action' => 'display',
-            'home'
+            'home',
         ]);
     }
+
+    return null;
 }
 ```

docs/en/password-hashers.md

@@ -60,21 +60,26 @@ access the `Password` identifier and check if the current user’s
 password needs to be upgraded:
 
 ``` php
-public function login()
+public function login(): ?\Cake\Http\Response
 {
     $authentication = $this->request->getAttribute('authentication');
     $result = $authentication->getResult();
 
-    // regardless of POST or GET, redirect if user is logged in
+    // Regardless of POST or GET, redirect if user is logged in
     if ($result->isValid()) {
         if ($authentication->getIdentificationProvider()->needsPasswordRehash()) {
             // Rehash happens on save.
-            $user = $this->Users->get($authentication->getIdentity()->getIdentifier());
+            $user = $this->fetchTable('Users')->get(
+                $authentication->getIdentity()->getIdentifier()
+            );
             $user->password = $this->request->getData('password');
-            $this->Users->saveOrFail($user);
+            $this->fetchTable('Users')->saveOrFail($user);
         }
 
         // Redirect or display a template.
+        return $this->redirect('/');
     }
+
+    return null;
 }
 ```

docs/en/testing.md

@@ -19,7 +19,7 @@ class ArticlesControllerTest extends TestCase
 ```
 
 Based on the type of authentication you're using you will need to
-simulate credentials differently. Lets review a few more common types of
+simulate credentials differently. Let's review a few more common types of
 authentication.
 
 ## Session based authentication
@@ -29,10 +29,9 @@ normally would be found in the session. In your test cases you can
 define a helper method that lets you 'login':
 
 ``` php
-protected function login($userId = 1)
+protected function login(int $userId = 1): void
 {
-    $users = TableRegistry::getTableLocator()->get('Users');
-    $user = $users->get($userId);
+    $user = $this->fetchTable('Users')->get($userId);
     $this->session(['Auth' => $user]);
 }
 ```
@@ -81,14 +80,14 @@ variables that [PHP creates](https://php.net/manual/en/features.http-auth.php)
 automatically:
 
 ``` php
-public function testGet()
+public function testGet(): void
 {
-     $this->configRequest([
-         'environment' => [
-             'PHP_AUTH_USER' => 'username',
-             'PHP_AUTH_PW' => 'password',
-         ]
-     ]);
+    $this->configRequest([
+        'environment' => [
+            'PHP_AUTH_USER' => 'username',
+            'PHP_AUTH_PW' => 'password',
+        ],
+    ]);
     $this->get('/api/bookmarks');
     $this->assertResponseOk();
 }