Fix documentation issues for 4.x

- Update AbstractIdentifier::CREDENTIAL_* to PasswordIdentifier::CREDENTIAL_*
- Add missing return types to code examples (initialize(), _setPassword())
- Fix broken tutorial link to use absolute CakePHP Book URL
- Replace deprecated strpos() with str_starts_with()
- Update API link from CakePHP 4.0 to 5
- Remove misleading identifier config from Session authenticator examples
- Remove outdated "Added in version 2.10.0" notes
- Add missing use statement for JWT in JwksController example
- Fix typo in jwt.pem path (./jwt.pem -> /jwt.pem)
- Use strict comparison (===) instead of loose (==)
- Add missing MiddlewareQueue type hints in migration guide
- Remove unused ResponseInterface import
- Add missing documentation links in contents.md (redirect-validation, upgrade-3-to-4)

Author: dereuromark

docs/en/authenticators.md

@@ -267,9 +267,11 @@ $builder->connect('/.well-known/:controller/*', [
 ]); // connect /.well-known/jwks.json to JwksController
 
 // controller/JwksController.php
+use Firebase\JWT\JWT;
+
 public function index()
 {
-    $pubKey = file_get_contents(CONFIG . './jwt.pem');
+    $pubKey = file_get_contents(CONFIG . '/jwt.pem');
     $res = openssl_pkey_get_public($pubKey);
     $detail = openssl_pkey_get_details($res);
     $key = [
@@ -344,7 +346,7 @@ Configuration options:
   - **samesite**: String/null The value for the same site attribute.
 
   The defaults for the various options besides `cookie.name` will be those
-  set for the `Cake\Http\Cookie\Cookie` class. See [Cookie::setDefaults()](https://api.cakephp.org/4.0/class-Cake.Http.Cookie.Cookie.html#setDefaults)
+  set for the `Cake\Http\Cookie\Cookie` class. See [Cookie::setDefaults()](https://api.cakephp.org/5/class-Cake.Http.Cookie.Cookie.html#setDefaults)
   for the default values.
 
 - **fields**: Array that maps `username` and `password` to the
@@ -377,8 +379,8 @@ authentication cookie is **also destroyed**. An example configuration would be:
 
 // Reuse fields in multiple authenticators.
 $fields = [
-    AbstractIdentifier::CREDENTIAL_USERNAME => 'email',
-    AbstractIdentifier::CREDENTIAL_PASSWORD => 'password',
+    PasswordIdentifier::CREDENTIAL_USERNAME => 'email',
+    PasswordIdentifier::CREDENTIAL_PASSWORD => 'password',
 ];
 
 // Put form authentication first so that users can re-login via
@@ -389,9 +391,7 @@ $service->loadAuthenticator('Authentication.Form', [
     'loginUrl' => '/users/login',
 ]);
 // Then use sessions if they are active.
-$service->loadAuthenticator('Authentication.Session', [
-    'identifier' => 'Authentication.Password',
-]);
+$service->loadAuthenticator('Authentication.Session');
 
 // If the user is on the login page, check for a cookie as well.
 $service->loadAuthenticator('Authentication.Cookie', [
@@ -441,9 +441,6 @@ $service->loadAuthenticator('Authentication.Environment', [
 ]);
 ```
 
-::: info Added in version 2.10.0
-`EnvironmentAuthenticator` was added.
-:::
 
 ## Events
 
@@ -549,9 +546,7 @@ $passwordIdentifier = [
 ];
 
 // Load the authenticators leaving Basic as the last one.
-$service->loadAuthenticator('Authentication.Session', [
-    'identifier' => $passwordIdentifier,
-]);
+$service->loadAuthenticator('Authentication.Session');
 $service->loadAuthenticator('Authentication.Form', [
     'identifier' => $passwordIdentifier,
 ]);
@@ -622,7 +617,7 @@ public function getAuthenticationService(
 
     // Configuration common to both the API and web goes here.
 
-    if ($request->getParam('prefix') == 'Api') {
+    if ($request->getParam('prefix') === 'Api') {
         // Include API specific authenticators
     } else {
         // Web UI specific authenticators.

docs/en/contents.md

@@ -12,6 +12,8 @@
 - [Testing with Authentication](testing)
 - [User Impersonation](impersonation)
 - [URL Checkers](url-checkers)
+- [Redirect Validation](redirect-validation)
 - [View Helper](view-helper)
 - [Migration from the AuthComponent](migration-from-the-authcomponent)
 - [Upgrading from 2.x to 3.x](upgrade-2-to-3)
+- [Upgrading from 3.x to 4.x](upgrade-3-to-4)

docs/en/impersonation.md

@@ -1,9 +1,5 @@
 # User Impersonation
 
-::: info Added in version 2.10.0
-User impersonation was added.
-:::
-
 After deploying your application, you may occasionally need to
 'impersonate' another user in order to debug problems that your customers report
 or to see the application in the state that your customers are seeing it.

docs/en/index.md

@@ -26,7 +26,7 @@ imports:
 use Authentication\AuthenticationService;
 use Authentication\AuthenticationServiceInterface;
 use Authentication\AuthenticationServiceProviderInterface;
-use Authentication\Identifier\AbstractIdentifier;
+use Authentication\Identifier\PasswordIdentifier;
 use Authentication\Middleware\AuthenticationMiddleware;
 use Cake\Http\MiddlewareQueue;
 use Cake\Routing\Router;
@@ -93,8 +93,8 @@ public function getAuthenticationService(ServerRequestInterface $request): Authe
     ]);
 
     $fields = [
-        AbstractIdentifier::CREDENTIAL_USERNAME => 'email',
-        AbstractIdentifier::CREDENTIAL_PASSWORD => 'password',
+        PasswordIdentifier::CREDENTIAL_USERNAME => 'email',
+        PasswordIdentifier::CREDENTIAL_PASSWORD => 'password',
     ];
 
     // Load the authenticators. Session should be first.
@@ -135,7 +135,7 @@ Next, in your `AppController` load the [Authentication Component](authentication
 
 ``` php
 // in src/Controller/AppController.php
-public function initialize()
+public function initialize(): void
 {
     parent::initialize();
 
@@ -156,7 +156,7 @@ $this->Authentication->allowUnauthenticated(['view', 'index']);
 ## Building a Login Action
 
 Once you have the middleware applied to your application you'll need a way for
-users to login. Please ensure your database has been created with the Users table structure used in [tutorial](tutorials-and-examples/cms/database). First generate a Users model and controller with bake:
+users to login. Please ensure your database has been created with the Users table structure used in the [CMS tutorial](https://book.cakephp.org/5/en/tutorials-and-examples/cms/database.html). First generate a Users model and controller with bake:
 
 ``` bash
 bin/cake bake model Users
@@ -240,9 +240,10 @@ class User extends Entity
     // ... other methods
 
     // Automatically hash passwords when they are changed.
-    protected function _setPassword(string $password)
+    protected function _setPassword(string $password): string
     {
         $hasher = new DefaultPasswordHasher();
+
         return $hasher->hash($password);
     }
 }

docs/en/middleware.md

@@ -37,7 +37,7 @@ public function getAuthenticationService(ServerRequestInterface $request): Authe
     $path = $request->getPath();
 
     $service = new AuthenticationService();
-    if (strpos($path, '/api') === 0) {
+    if (str_starts_with($path, '/api')) {
         // Accept API tokens only
         $service->loadAuthenticator('Authentication.Token', [
             'identifier' => 'Authentication.Token',

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

@@ -75,7 +75,6 @@ use Authentication\AuthenticationService;
 use Authentication\AuthenticationServiceInterface;
 use Authentication\AuthenticationServiceProviderInterface;
 use Authentication\Middleware\AuthenticationMiddleware;
-use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
 
 // Add the authentication interface.
@@ -101,7 +100,7 @@ Next add the `AuthenticationMiddleware` to your application:
 
 ``` php
 // in src/Application.php
-public function middleware($middlewareQueue)
+public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue
 {
     // Various other middlewares for error handling, routing etc. added here.
 
@@ -147,13 +146,11 @@ $service = new AuthenticationService();
      ],
  ];
 
- // Load the authenticators
- $service->loadAuthenticator('Authentication.Session', [
-     'identifier' => $passwordIdentifier,
- ]);
- $service->loadAuthenticator('Authentication.Form', [
-     'identifier' => $passwordIdentifier,
- ]);
+// Load the authenticators. Session should be first.
+$service->loadAuthenticator('Authentication.Session');
+$service->loadAuthenticator('Authentication.Form', [
+    'identifier' => $passwordIdentifier,
+]);
 ```
 
 If you have customized the `userModel` you can use the following