Fix up Url Checker defaulting.

Author: mscherer

docs/en/upgrade-3-to-4.rst

@@ -105,16 +105,20 @@ For LDAP authentication:
         LdapIdentifier::CREDENTIAL_PASSWORD => 'password',
     ];
 
-URL Checker Renamed
--------------------
+URL Checker Renamed and Restructured
+-------------------------------------
 
-``CakeRouterUrlChecker`` has been renamed to ``CakeUrlChecker`` and now accepts
-both string and array URLs (just like ``Router::url()``).
+URL checkers have been completely restructured:
+
+- ``CakeRouterUrlChecker`` has been renamed to ``DefaultUrlChecker``
+- The old ``DefaultUrlChecker`` (framework-agnostic) has been renamed to ``GenericUrlChecker``
+- Auto-detection has been removed - ``DefaultUrlChecker`` is now hardcoded
 
 **Before (3.x):**
 
 .. code-block:: php
 
+    // Using CakeRouterUrlChecker explicitly
     $service->loadAuthenticator('Authentication.Form', [
         'urlChecker' => 'Authentication.CakeRouter',
         'loginUrl' => [
@@ -123,25 +127,33 @@ both string and array URLs (just like ``Router::url()``).
         ],
     ]);
 
+    // Using DefaultUrlChecker explicitly (framework-agnostic)
+    $service->loadAuthenticator('Authentication.Form', [
+        'urlChecker' => 'Authentication.Default',
+        'loginUrl' => '/users/login',
+    ]);
+
+    // Auto-detection (picks CakeRouter if available, otherwise Default)
+    $service->loadAuthenticator('Authentication.Form', [
+        'loginUrl' => '/users/login',
+    ]);
+
 **After (4.x):**
 
 .. code-block:: php
 
-    // CakeUrlChecker is now the default when CakePHP is installed
+    // DefaultUrlChecker is now hardcoded (formerly CakeRouterUrlChecker)
     $service->loadAuthenticator('Authentication.Form', [
         'loginUrl' => [
             'controller' => 'Users',
             'action' => 'login',
         ],
     ]);
 
-    // Or explicitly:
+    // For framework-agnostic projects, explicitly use GenericUrlChecker
     $service->loadAuthenticator('Authentication.Form', [
-        'urlChecker' => 'Authentication.Cake',
-        'loginUrl' => [
-            'controller' => 'Users',
-            'action' => 'login',
-        ],
+        'urlChecker' => 'Authentication.Generic',
+        'loginUrl' => '/users/login',
     ]);
 
 Simplified URL Checker API
@@ -189,31 +201,38 @@ Single URLs work the same in both versions:
         'loginUrl' => ['controller' => 'Users', 'action' => 'login'],
     ]);
 
-Auto-Detection Changes
+Auto-Detection Removed
 ----------------------
 
 URL Checkers
 ^^^^^^^^^^^^
 
-- When CakePHP Router is available: defaults to ``CakeUrlChecker``
-- Without CakePHP: defaults to ``DefaultUrlChecker``
-- For multiple URLs: you **must** explicitly configure ``MultiUrlChecker``
+**Important:** Auto-detection has been removed. ``DefaultUrlChecker`` is now hardcoded
+and assumes CakePHP is available.
+
+- **4.x default:** Always uses ``DefaultUrlChecker`` (formerly ``CakeUrlChecker``)
+- **Framework-agnostic:** Must explicitly configure ``GenericUrlChecker``
+- **Multiple URLs:** Must explicitly configure ``MultiUrlChecker``
 
-DefaultUrlChecker Changes
-^^^^^^^^^^^^^^^^^^^^^^^^^
+DefaultUrlChecker is Now CakePHP-Based
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-``DefaultUrlChecker`` no longer accepts array-based URLs. It throws a
-``RuntimeException`` if an array URL is provided:
+``DefaultUrlChecker`` is now the CakePHP checker (formerly ``CakeRouterUrlChecker``).
+It requires CakePHP Router and supports both string and array URLs.
+
+The 3.x framework-agnostic ``DefaultUrlChecker`` has been renamed to ``GenericUrlChecker``.
 
 .. code-block:: php
 
-    // This will throw an exception in 4.x
+    // DefaultUrlChecker now requires CakePHP Router
     $checker = new DefaultUrlChecker();
-    $checker->check($request, ['controller' => 'Users', 'action' => 'login']);
+    $checker->check($request, ['controller' => 'Users', 'action' => 'login']);  // Works
+    $checker->check($request, '/users/login');  // Also works
 
-    // Use CakeUrlChecker instead:
-    $checker = new CakeUrlChecker();
-    $checker->check($request, ['controller' => 'Users', 'action' => 'login']);
+    // For framework-agnostic usage:
+    $checker = new GenericUrlChecker();
+    $checker->check($request, '/users/login');  // Works
+    $checker->check($request, ['controller' => 'Users']);  // Throws exception
 
 New Features
 ============
@@ -264,20 +283,33 @@ Migration Tips
 
    - ``AbstractIdentifier::CREDENTIAL_`` → ``PasswordIdentifier::CREDENTIAL_``
    - ``IdentifierCollection`` → ``IdentifierFactory``
-   - ``'Authentication.CakeRouter'`` → ``'Authentication.Cake'``
-   - ``CakeRouterUrlChecker`` → ``CakeUrlChecker``
+   - ``'Authentication.CakeRouter'`` → Remove (no longer needed, default is now CakePHP-based)
+   - ``CakeRouterUrlChecker`` → ``DefaultUrlChecker``
+   - Old 3.x ``DefaultUrlChecker`` (framework-agnostic) → ``GenericUrlChecker``
+
+2. **Framework-Agnostic Projects**:
+
+   If you're using this library without CakePHP, you **must** explicitly configure
+   ``GenericUrlChecker``:
+
+   .. code-block:: php
+
+       $service->loadAuthenticator('Authentication.Form', [
+           'urlChecker' => 'Authentication.Generic',
+           'loginUrl' => '/users/login',
+       ]);
 
-2. **Multiple Login URLs**:
+3. **Multiple Login URLs**:
 
    If you have multiple login URLs, add ``'urlChecker' => 'Authentication.Multi'``
    to your authenticator configuration.
 
-3. **Custom Identifier Setup**:
+4. **Custom Identifier Setup**:
 
    If you were passing ``IdentifierCollection`` to authenticators, switch to
    either passing a single identifier or null (to use defaults).
 
-4. **Test Thoroughly**:
+5. **Test Thoroughly**:
 
    The changes to identifier management and URL checking are significant.
    Test all authentication flows after upgrading.

docs/en/url-checkers.rst

@@ -11,11 +11,11 @@ For multiple login URLs, use ``MultiUrlChecker``.
 Included Checkers
 =================
 
-CakeUrlChecker
---------------
+DefaultUrlChecker
+-----------------
 
-The default checker when CakePHP is installed. Supports both string URLs and
-CakePHP's array-based routing notation. This checker also works with named routes.
+The default URL checker. Supports both string URLs and CakePHP's array-based
+routing notation. Uses CakePHP Router and works with named routes.
 
 Single URL (string):
 
@@ -41,18 +41,18 @@ Single URL (CakePHP route array):
 Options:
 
 -  **checkFullUrl**: To compare the full URL, including protocol, host
-   and port or not. Default is ``false``
+   and port or not. Default is ``false``.
 
-DefaultUrlChecker
------------------
+GenericUrlChecker
+------------------
 
 Framework-agnostic checker for string URLs. Supports regex matching.
-This is the default when CakePHP is not installed.
+Use this for non-CakePHP projects.
 
 .. code-block:: php
 
     $service->loadAuthenticator('Authentication.Form', [
-        'urlChecker' => 'Authentication.Default',
+        'urlChecker' => 'Authentication.Generic',
         'loginUrl' => '/users/login',
     ]);
 
@@ -62,7 +62,7 @@ Using regex:
 
     $service->loadAuthenticator('Authentication.Form', [
         'urlChecker' => [
-            'className' => 'Authentication.Default',
+            'className' => 'Authentication.Generic',
             'useRegex' => true,
         ],
         'loginUrl' => '%^/[a-z]{2}/users/login/?$%',

src/Authenticator/FormAuthenticator.php

@@ -42,7 +42,7 @@ class FormAuthenticator extends AbstractAuthenticator
      */
     protected array $_defaultConfig = [
         'loginUrl' => null,
-        'urlChecker' => 'Authentication.Cake',
+        'urlChecker' => null,
         'fields' => [
             PasswordIdentifier::CREDENTIAL_USERNAME => 'username',
             PasswordIdentifier::CREDENTIAL_PASSWORD => 'password',

src/UrlChecker/CakeUrlChecker.php

@@ -16,24 +16,22 @@
  */
 namespace Authentication\UrlChecker;
 
+use Cake\Routing\Router;
 use Psr\Http\Message\ServerRequestInterface;
-use RuntimeException;
 
 /**
- * Checks if a request object contains a valid URL. Framework agnostic.
+ * Default URL checker for CakePHP applications. Uses CakePHP Router.
  */
 class DefaultUrlChecker implements UrlCheckerInterface
 {
     /**
      * Default Options
      *
-     * - `urlChecker` Whether to use `loginUrl` as regular expression(s).
      * - `checkFullUrl` Whether to check the full request URI.
      *
      * @var array<string, mixed>
      */
     protected array $_defaultOptions = [
-        'useRegex' => false,
         'checkFullUrl' => false,
     ];
 
@@ -42,52 +40,26 @@ class DefaultUrlChecker implements UrlCheckerInterface
      */
     public function check(ServerRequestInterface $request, array|string $loginUrls, array $options = []): bool
     {
-        if (is_array($loginUrls)) {
-            throw new RuntimeException(
-                'Array-based login URLs require CakePHP Router and CakeUrlChecker. ' .
-                'Either install cakephp/cakephp or use string URLs instead.',
-            );
-        }
-
         $options = $this->_mergeDefaultOptions($options);
-        $checker = $this->_getChecker($options);
         $url = $this->_getUrlFromRequest($request, $options['checkFullUrl']);
 
-        return (bool)$checker($loginUrls, $url);
+        // Support both string URLs and array-based routes (like Router::url())
+        $validUrl = Router::url($loginUrls, $options['checkFullUrl']);
+
+        return $validUrl === $url;
     }
 
     /**
      * Merges given options with the defaults.
      *
-     * The reason this method exists is that it makes it easy to override the
-     * method and inject additional options without the need to use the
-     * MergeVarsTrait.
-     *
      * @param array<string, mixed> $options Options to merge in
-     * @return array
+     * @return array<string, mixed>
      */
     protected function _mergeDefaultOptions(array $options): array
     {
         return $options + $this->_defaultOptions;
     }
 
-    /**
-     * Gets the checker function name or a callback
-     *
-     * @param array<string, mixed> $options Array of options
-     * @return callable
-     */
-    protected function _getChecker(array $options): callable
-    {
-        if (!empty($options['useRegex'])) {
-            return 'preg_match';
-        }
-
-        return function ($validUrl, $url) {
-            return $validUrl === $url;
-        };
-    }
-
     /**
      * Returns current url.
      *