Add Router::matchRequest convenience entry point

Router::matchRoute() takes (method, path) strings, forcing every caller
to hand-roll URL parsing and HEAD-to-GET normalisation. The library
already does this internally in Dispatcher::handle; the matching
boilerplate should not be the caller's problem.

Router::matchRequest(Request) wraps matchRoute and handles both. The
deprecated Http::match() shim now delegates to it; Dispatcher continues
to call matchRoute directly because it needs the parsed URL in scope
for the wildcard fallback anyway.

Adds three regression tests covering URL extraction, root-URL fallback
when the URI has no path, and HEAD normalisation.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: loks0n

src/Http/Http.php

@@ -531,19 +531,14 @@ public function start(): void
     }
 
     /**
-     * @deprecated Use {@see Router::matchRoute()} which returns a per-request
-     *   {@see RouteMatch}. This shim discards the `$fresh` argument: the
-     *   previous implementation cached the match on the Http singleton,
-     *   which is not safe under concurrent request handling.
+     * @deprecated Use {@see Router::matchRequest()} which returns a
+     *   per-request {@see RouteMatch}. This shim discards the `$fresh`
+     *   argument: the previous implementation cached the match on the Http
+     *   singleton, which is not safe under concurrent request handling.
      */
     public function match(Request $request, bool $fresh = true): ?Route
     {
-        $url = \parse_url($request->getURI(), PHP_URL_PATH);
-        $url = \is_string($url) ? ($url === '' ? '/' : $url) : '/';
-        $method = $request->getMethod();
-        $method = (self::REQUEST_METHOD_HEAD === $method) ? self::REQUEST_METHOD_GET : $method;
-
-        $match = Router::matchRoute($method, $url);
+        $match = Router::matchRequest($request);
         if ($match === null) {
             return null;
         }

src/Http/Router.php

@@ -159,6 +159,26 @@ public static function matchRoute(string $method, string $path): ?RouteMatch
         return null;
     }
 
+    /**
+     * Match a {@see Request} against the router.
+     *
+     * Convenience wrapper around {@see Router::matchRoute()} that extracts
+     * the path from the request URI and normalises HEAD to GET (the
+     * HEAD method is served by the GET handler with the response payload
+     * disabled). Prefer this over hand-rolling the parse + HEAD logic at
+     * every call site.
+     */
+    public static function matchRequest(Request $request): ?RouteMatch
+    {
+        $url = \parse_url($request->getURI(), PHP_URL_PATH);
+        $url = \is_string($url) ? ($url === '' ? '/' : $url) : '/';
+
+        $method = $request->getMethod();
+        $method = ($method === Http::REQUEST_METHOD_HEAD) ? Http::REQUEST_METHOD_GET : $method;
+
+        return self::matchRoute($method, $url);
+    }
+
     /**
      * @deprecated Use {@see Router::matchRoute()} which returns a per-request
      *   {@see RouteMatch}. The old signature returned the shared Route

tests/RouterMatchRouteTest.php

@@ -5,6 +5,7 @@
 namespace Utopia\Http;
 
 use PHPUnit\Framework\TestCase;
+use Utopia\Http\Adapter\FPM\Request;
 
 /**
  * Coverage for {@see Router::matchRoute()} — the coroutine-safe replacement
@@ -124,6 +125,50 @@ public function testTwoMatchesReturnDistinctRouteMatchInstances(): void
         $this->assertSame('/users/2', $b->urlPath);
     }
 
+    public function testMatchRequestExtractsPathFromUri(): void
+    {
+        $route = new Route('GET', '/users/:id');
+        Router::addRoute($route);
+
+        $_SERVER['REQUEST_METHOD'] = 'GET';
+        $_SERVER['REQUEST_URI'] = '/users/42?extra=ignored';
+
+        $match = Router::matchRequest(new Request());
+
+        $this->assertNotNull($match);
+        $this->assertSame($route, $match->route);
+        $this->assertSame('/users/42', $match->urlPath);
+    }
+
+    public function testMatchRequestDefaultsEmptyPathToSlash(): void
+    {
+        $route = new Route('GET', '/');
+        Router::addRoute($route);
+
+        $_SERVER['REQUEST_METHOD'] = 'GET';
+        $_SERVER['REQUEST_URI'] = 'https://example.com?x=1';
+
+        $match = Router::matchRequest(new Request());
+
+        $this->assertNotNull($match);
+        $this->assertSame($route, $match->route);
+        $this->assertSame('/', $match->urlPath);
+    }
+
+    public function testMatchRequestNormalisesHeadToGet(): void
+    {
+        $route = new Route('GET', '/head-target');
+        Router::addRoute($route);
+
+        $_SERVER['REQUEST_METHOD'] = 'HEAD';
+        $_SERVER['REQUEST_URI'] = '/head-target';
+
+        $match = Router::matchRequest(new Request());
+
+        $this->assertNotNull($match);
+        $this->assertSame($route, $match->route, 'HEAD must resolve against the GET route.');
+    }
+
     public function testLegacyShimReturnsRoute(): void
     {
         $route = new Route('GET', '/shim');