Update for CakePHP 6

.github/workflows/ci.yml

@@ -5,6 +5,8 @@ on:
     branches:
       - 3.x
       - 3.next
+      - 4.x
+      - 5.x
   pull_request:
     branches:
       - '*'
@@ -15,9 +17,9 @@ permissions:
 
 jobs:
   testsuite:
-    uses: cakephp/.github/.github/workflows/testsuite-without-db.yml@5.x
+    uses: cakephp/.github/.github/workflows/testsuite-without-db.yml@6.x
     secrets: inherit
 
   cs-stan:
-    uses: cakephp/.github/.github/workflows/cs-stan.yml@5.x
+    uses: cakephp/.github/.github/workflows/cs-stan.yml@6.x
     secrets: inherit

.phive/phars.xml

@@ -1,4 +1,4 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <phive xmlns="https://phar.io/phive">
-  <phar name="phpstan" version="2.1.55" installed="2.1.55" location="./tools/phpstan" copy="false"/>
+  <phar name="phpstan" version="2.2.14" installed="2.2.14" location="./tools/phpstan" copy="false"/>
 </phive>

composer.json

@@ -20,23 +20,23 @@
         "issues": "https://github.com/cakephp/authentication/issues",
         "forum": "https://discourse.cakephp.org/",
         "source": "https://github.com/cakephp/authentication",
-        "docs": "https://book.cakephp.org/authentication/4/en/"
+        "docs": "https://book.cakephp.org/authentication/5/"
     },
     "require": {
-        "php": ">=8.1",
-        "cakephp/http": "^5.0",
-        "cakephp/utility": "^5.0",
+        "php": ">=8.4",
+        "cakephp/http": "^6.0",
+        "cakephp/utility": "^6.0",
         "laminas/laminas-diactoros": "^3.0",
         "psr/http-client": "^1.0",
         "psr/http-message": "^1.1 || ^2.0",
         "psr/http-server-handler": "^1.0",
         "psr/http-server-middleware": "^1.0"
     },
     "require-dev": {
-        "cakephp/cakephp": "^5.1.0",
-        "cakephp/cakephp-codesniffer": "^5.0",
+        "cakephp/cakephp": "^6.0",
+        "cakephp/cakephp-codesniffer": "^6.0",
         "firebase/php-jwt": "^7.0",
-        "phpunit/phpunit": "^10.5.58 || ^11.5.3 || ^12.4 || ^13.0"
+        "phpunit/phpunit": "^12.4 || ^13.0"
     },
     "suggest": {
         "ext-ldap": "Make sure this php extension is installed and enabled on your system if you want to use the built-in LDAP adapter for \"LdapIdentifier\".",
@@ -75,10 +75,12 @@
         "stan": "@phpstan",
         "stan-baseline": "tools/phpstan --generate-baseline",
         "stan-setup": "phive install",
-        "rector-setup": "cp composer.json composer.backup && composer require --dev rector/rector:\"~2.3.1\" && mv composer.backup composer.json",
+        "rector-setup": "cp composer.json composer.backup && composer require --dev rector/rector:\"~2.6.0\" && mv composer.backup composer.json",
         "rector-check": "vendor/bin/rector process --dry-run",
         "rector-fix": "vendor/bin/rector process",
         "test": "phpunit",
         "test-coverage": "phpunit --coverage-clover=clover.xml"
-    }
+    },
+    "minimum-stability": "dev",
+    "prefer-stable": true
 }

docs/.vitepress/config.js

@@ -5,9 +5,10 @@ const require = createRequire(import.meta.url);
 const toc_en = require("./toc_en.json");
 
 const versions = {
-  text: "4.x",
+  text: "5.x",
   items: [
-    { text: "4.x (current)", link: "https://book.cakephp.org/authentication/4/", target: '_self' },
+    { text: "5.x (current)", link: "https://book.cakephp.org/authentication/5/", target: '_self' },
+    { text: "4.x", link: "https://book.cakephp.org/authentication/4/", target: '_self' },
     { text: "3.x", link: "https://book.cakephp.org/authentication/3/en/", target: '_self' },
     { text: "2.x", link: "https://book.cakephp.org/authentication/2/en/", target: '_self' },
   ],
@@ -19,12 +20,12 @@ export default {
   srcDir: 'en',
   title: 'Authentication plugin',
   description: 'Authentication - CakePHP Authentication Plugin Documentation',
-  base: "/authentication/4/",
+  base: "/authentication/5/",
   rewrites: {
     "en/:slug*": ":slug*",
   },
   sitemap: {
-    hostname: "https://book.cakephp.org/authentication/4/",
+    hostname: "https://book.cakephp.org/authentication/5/",
   },
   themeConfig: {
     siteTitle: false,
@@ -33,7 +34,7 @@ export default {
       { icon: "github", link: "https://github.com/cakephp/authentication" },
     ],
     editLink: {
-      pattern: "https://github.com/cakephp/authentication/edit/4.x/docs/:path",
+      pattern: "https://github.com/cakephp/authentication/edit/5.x/docs/:path",
       text: "Edit this page on GitHub",
     },
     sidebar: toc_en,

docs/.vitepress/toc_en.json

@@ -42,7 +42,8 @@
       "collapsed": true,
       "items": [
         { "text": "Upgrading from 2.x to 3.x", "link": "/upgrade-2-to-3" },
-        { "text": "Upgrading from 3.x to 4.x", "link": "/upgrade-3-to-4" }
+        { "text": "Upgrading from 3.x to 4.x", "link": "/upgrade-3-to-4" },
+        { "text": "Upgrading from 4.x to 5.x", "link": "/upgrade-4-to-5" }
       ]
     }
   ]

docs/en/authenticators.md

@@ -356,7 +356,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/5/class-Cake.Http.Cookie.Cookie.html#setDefaults)
+  set for the `Cake\Http\Cookie\Cookie` class. See [Cookie::setDefaults()](https://api.cakephp.org/6.0/class-Cake.Http.Cookie.Cookie.html#setDefaults)
   for the default values.
 
 - **fields**: Array that maps `username` and `password` to the
@@ -468,7 +468,7 @@ There is only one event that is fired by authentication:
 `Authentication.afterIdentify`.
 
 If you don’t know what events are and how to use them [check the
-documentation](https://book.cakephp.org/5/en/core-libraries/events.html).
+documentation](https://book.cakephp.org/6/en/core-libraries/events.html).
 
 The `Authentication.afterIdentify` event is fired by the
 `AuthenticationComponent` after an identity was successfully

docs/en/contents.md

@@ -17,3 +17,4 @@
 - [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)
+- [Upgrading from 4.x to 5.x](upgrade-4-to-5)

docs/en/identifiers.md

@@ -168,7 +168,7 @@ Configuration options:
 - **userModel**: The user model identities are located in. Default is
   `Users`.
 - **finder**: The finder to use with the model. Default is `all`.
-  You can read more about model finders [here](https://book.cakephp.org/5/en/orm/retrieving-data-and-resultsets.html#custom-finder-methods).
+  You can read more about model finders [here](https://book.cakephp.org/6/en/orm/retrieving-data-and-resultsets.html#custom-finder-methods).
 
 In order to use ORM resolver you must require `cakephp/orm` in your
 `composer.json` file (if you are not already using the full CakePHP framework).

docs/en/index.md

@@ -7,7 +7,7 @@ Project's ROOT directory (where the **composer.json** file is located)
 php composer.phar require cakephp/authentication
 ```
 
-Version 4 of the Authentication Plugin is compatible with CakePHP 5.
+Version 5 of the Authentication Plugin is compatible with CakePHP 6.
 
 Load the plugin using the following command:
 
@@ -17,7 +17,7 @@ bin/cake plugin load Authentication
 
 ## Getting Started
 
-The authentication plugin integrates with your application as a [middleware](https://book.cakephp.org/5/en/controllers/middleware.html). It can also
+The authentication plugin integrates with your application as a [middleware](https://book.cakephp.org/6/en/controllers/middleware.html). It can also
 be used as a component to make unauthenticated access simpler. First, let's
 apply the middleware. In **src/Application.php**, add the following to the class
 imports:
@@ -157,7 +157,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 the [CMS tutorial](https://book.cakephp.org/5/en/tutorials-and-examples/cms/database.html). 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/6/en/tutorials-and-examples/cms/database.html). First generate a Users model and controller with bake:
 
 ```bash
 bin/cake bake model Users

docs/en/upgrade-4-to-5.md

@@ -0,0 +1,197 @@
+# Upgrade Guide 4.x to 5.x
+
+Version 5.0 of the Authentication plugin adds support for CakePHP 6.
+Application code that only uses the public API rarely needs to change, but
+the plugin's classes follow the CakePHP 6 convention changes, so custom
+subclasses need to be updated.
+
+## Requirements
+
+Version 5.x requires:
+
+- PHP 8.4 or higher
+- CakePHP 6.x, provided by `cakephp/http` and `cakephp/utility` 6.x
+- PHPUnit 12.4 or higher when you run the plugin's tests
+
+```bash
+composer require cakephp/authentication:^5.0
+```
+
+Upgrade your application to CakePHP 6 first by following the
+[CakePHP 6.0 Upgrade Guide](https://book.cakephp.org/6/en/appendices/6-0-upgrade-guide.html),
+then install version 5 of this plugin.
+
+## Breaking Changes
+
+### Leading Underscore Removed From Properties
+
+Following CakePHP 6, protected properties no longer start with an underscore.
+Update any custom subclass that reads or writes these properties.
+
+| Old (4.x) | New (5.x) |
+| --------- | --------- |
+| `$_defaultConfig` | `$defaultConfig` |
+| `$_defaultOptions` | `$defaultOptions` |
+| `$_identifier` | `$identifier` |
+| `$_authentication` | `$authentication` |
+| `$_authenticators` | `$authenticators` |
+| `$_successfulAuthenticator` | `$successfulAuthenticator` |
+| `$_result` | `$result` |
+| `$_identity` | `$identity` |
+| `$_passwordHasher` | `$passwordHasher` |
+| `$_needsPasswordRehash` | `$needsPasswordRehash` |
+| `$_hashers` | `$hashers` |
+| `$_errors` | `$errors` |
+| `$_data` | `$data` |
+| `$_status` | `$status` |
+| `$_connection` | `$connection` |
+| `$_ldap` | `$ldap` |
+| `$_loaded` | `$loaded` |
+
+`$defaultConfig` is declared by the authenticators, identifiers, password
+hashers, URL checkers, `AbstractCollection`, `AuthenticationService`,
+`AuthenticationComponent`, `Identity` and `IdentityHelper`. The `$config`
+property that comes from CakePHP's `InstanceConfigTrait` lost its underscore as
+well.
+
+**Before (4.x):**
+
+```php
+class CustomAuthenticator extends AbstractAuthenticator
+{
+    protected array $_defaultConfig = [
+        'fields' => ['username' => 'email'],
+    ];
+
+    public function example(): void
+    {
+        $fields = $this->_defaultConfig['fields'];
+    }
+}
+```
+
+**After (5.x):**
+
+```php
+class CustomAuthenticator extends AbstractAuthenticator
+{
+    protected array $defaultConfig = [
+        'fields' => ['username' => 'email'],
+    ];
+
+    public function example(): void
+    {
+        $fields = $this->defaultConfig['fields'];
+    }
+}
+```
+
+### Leading Underscore Removed From Methods
+
+The same rename applies to the plugin's protected methods.
+
+| Old (4.x) | New (5.x) | Class |
+| --------- | --------- | ----- |
+| `$_authenticateLegacyToken()` | `authenticateLegacyToken()` | `CookieAuthenticator` |
+| `$_authenticateToken()` | `authenticateToken()` | `CookieAuthenticator` |
+| `$_bindUser()` | `bindUser()` | `LdapIdentifier` |
+| `$_buildLdapObject()` | `buildLdapObject()` | `LdapIdentifier` |
+| `$_buildLoginUrlErrorResult()` | `buildLoginUrlErrorResult()` | `EnvironmentAuthenticator`, `FormAuthenticator` |
+| `$_checkLdapConfig()` | `checkLdapConfig()` | `LdapIdentifier` |
+| `$_checkPassword()` | `checkPassword()` | `PasswordIdentifier` |
+| `$_checkSingleUrl()` | `checkSingleUrl()` | `MultiUrlChecker` |
+| `$_checkUrl()` | `checkUrl()` | `UrlCheckerTrait` |
+| `$_connectLdap()` | `connectLdap()` | `LdapIdentifier` |
+| `$_create()` | `create()` | `AuthenticatorCollection` |
+| `$_createCookie()` | `createCookie()` | `CookieAuthenticator` |
+| `$_createLegacyPlainToken()` | `createLegacyPlainToken()` | `CookieAuthenticator` |
+| `$_createToken()` | `createToken()` | `CookieAuthenticator` |
+| `$_expiryTimestamp()` | `expiryTimestamp()` | `CookieAuthenticator` |
+| `$_findIdentity()` | `findIdentity()` | `PasswordIdentifier` |
+| `$_getChecker()` | `getChecker()` | `StringUrlChecker` |
+| `$_getData()` | `getData()` | `FormAuthenticator` |
+| `$_getUrlFromRequest()` | `getUrlFromRequest()` | `DefaultUrlChecker`, `StringUrlChecker` |
+| `$_handleLdapError()` | `handleLdapError()` | `LdapIdentifier` |
+| `$_hmacKey()` | `hmacKey()` | `CookieAuthenticator` |
+| `$_isSingleRoute()` | `isSingleRoute()` | `MultiUrlChecker` |
+| `$_legacyHashWithinLimits()` | `legacyHashWithinLimits()` | `CookieAuthenticator` |
+| `$_mergeDefaultOptions()` | `mergeDefaultOptions()` | `DefaultUrlChecker`, `MultiUrlChecker`, `StringUrlChecker` |
+| `$_resolveClassName()` | `resolveClassName()` | `AuthenticatorCollection` |
+| `$_setErrorHandler()` | `setErrorHandler()` | `ExtensionAdapter` |
+| `$_throwMissingClassError()` | `throwMissingClassError()` | `AuthenticatorCollection` |
+| `$_unsetErrorHandler()` | `unsetErrorHandler()` | `ExtensionAdapter` |
+
+The [cakephp/upgrade](https://github.com/cakephp/upgrade) tool knows about the
+CakePHP 6 renames and can apply most of them for you.
+
+### Fluent Methods Now Return `static`
+
+These methods now declare a `static` return type. If you override any of them,
+add the same return type to your override:
+
+- `AuthenticationComponent::allowUnauthenticated()`
+- `AuthenticationComponent::addUnauthenticatedActions()`
+- `AuthenticationComponent::setIdentity()`
+- `AuthenticationComponent::replaceIdentity()`
+- `AuthenticationComponent::impersonate()`
+- `AuthenticationComponent::stopImpersonating()`
+- `AbstractAuthenticator::setIdentifier()`
+- `PasswordHasherTrait::setPasswordHasher()`
+- `ResolverAwareTrait::setResolver()`
+
+**Before (4.x):**
+
+```php
+class CustomComponent extends AuthenticationComponent
+{
+    public function allowUnauthenticated(array $actions)
+    {
+        return parent::allowUnauthenticated($actions);
+    }
+}
+```
+
+**After (5.x):**
+
+```php
+class CustomComponent extends AuthenticationComponent
+{
+    public function allowUnauthenticated(array $actions): static
+    {
+        return parent::allowUnauthenticated($actions);
+    }
+}
+```
+
+### Constructor Changes
+
+- The third argument of `Result::__construct()` was renamed from `$messages`
+  to `$errors`. Named arguments such as `messages:` must be updated.
+- The second argument of `AuthenticationMiddleware::__construct()` is typed as
+  `Cake\Container\ContainerInterface` instead of `Cake\Core\ContainerInterface`.
+- `AbstractAuthenticator`, `AuthenticationMiddleware`, `AuthenticationRequiredException`,
+  `Identity` and `Result` use constructor promoted properties now. Subclasses
+  that override these constructors should call `parent::__construct()` with the
+  same arguments as before.
+
+## Migration Tips
+
+1. **Upgrade CakePHP first**: Finish the
+   [CakePHP 6.0 Upgrade Guide](https://book.cakephp.org/6/en/appendices/6-0-upgrade-guide.html)
+   and resolve all deprecation warnings while you are still on CakePHP 5.
+
+2. **Search and replace** the renamed members in your custom authenticators,
+   identifiers, password hashers, URL checkers and components:
+
+    - `$_defaultConfig` → `$defaultConfig`
+    - `$_defaultOptions` → `$defaultOptions`
+    - `$_identifier` → `$identifier`
+    - `$_config` → `$config`
+    - `$this->_checkUrl(` → `$this->checkUrl(`
+    - Any other `$_method()` or `$_property` of the plugin's classes
+
+3. **Add return types** to overridden fluent methods so they match the new
+   `static` return types.
+
+4. **Run your test suite** with the new dependencies to find remaining
+   references to the old names.

phpcs.xml

@@ -5,7 +5,7 @@
     <file>src/</file>
     <file>tests/</file>
 
-    <arg value="nps"/>
+    <arg value="ps"/>
     <arg name="colors"/>
     <arg name="parallel" value="4"/>
     <arg name="cache" value=".phpcs.cache"/>