(feat): method aliases for routes via aliasMethod()

ChiragAgg5k · ChiragAgg5k · commit 7618804bd1ce · 2026-06-10T09:08:03.000+05:30
diff --git a/README.md b/README.md
@@ -143,6 +143,37 @@ curl http://localhost:8000/hello-world?name=Appwrite
 
 It's always recommended to use params instead of getting params or body directly from the request resource. If you do that intentionally, always make sure to run validation right after fetching such a raw input.
 
+### Aliases
+
+A route can be registered under additional paths and HTTP methods using aliases. All aliases dispatch to the same route, so the action, params, and hooks are defined only once.
+
+Use `alias()` to serve the same route under another path, for example to keep a legacy URL working:
+
+```php
+Http::get('/users/:id')
+    ->alias('/members/:id')
+    ->param('id', '', new Text(256), 'User ID')
+    ->inject('response')
+    ->action(function(string $id, Response $response) {
+        $response->json(['id' => $id]);
+    });
+```
+
+Use `aliasMethod()` to serve the same route under another HTTP method. For example, the OpenID Connect UserInfo endpoint must support both GET and POST:
+
+```php
+Http::get('/oauth/userinfo')
+    ->aliasMethod(Http::REQUEST_METHOD_POST)
+    ->inject('request')
+    ->inject('response')
+    ->action(function(Request $request, Response $response) {
+        // $request->getMethod() tells how the request arrived (GET or POST)
+        $response->json(['sub' => 'user-id']);
+    });
+```
+
+Path and method aliases combine: a route with both responds on every method under every path. Note that `getMethod()` on the route keeps returning the primary method it was defined with; use the request resource to tell how a request arrived.
+
 ### Hooks
 
 There are three types of hooks:
diff --git a/src/Http/Route.php b/src/Http/Route.php
@@ -28,6 +28,20 @@ class Route extends Hook
      */
     protected array $pathParams = [];
 
+    /**
+     * Alias paths this route is also registered under.
+     *
+     * @var array<string>
+     */
+    protected array $aliasPaths = [];
+
+    /**
+     * Alias HTTP methods this route is also registered under.
+     *
+     * @var array<string>
+     */
+    protected array $aliasMethods = [];
+
     /**
      * Internal counter.
      */
@@ -71,6 +85,31 @@ public function alias(string $path): self
     {
         Router::addRouteAlias($path, $this);
 
+        foreach ($this->aliasMethods as $method) {
+            Router::addRouteAlias($path, $this, $method);
+        }
+
+        $this->aliasPaths[] = $path;
+
+        return $this;
+    }
+
+    /**
+     * Register this route under an additional HTTP method.
+     *
+     * The route keeps reporting its primary method via getMethod();
+     * use the request's method to tell how a request arrived.
+     */
+    public function aliasMethod(string $method): self
+    {
+        Router::addRouteMethodAlias($method, $this);
+
+        foreach ($this->aliasPaths as $path) {
+            Router::addRouteAlias($path, $this, $method);
+        }
+
+        $this->aliasMethods[] = $method;
+
         return $this;
     }
 
@@ -108,6 +147,26 @@ public function getHook(): bool
         return $this->hook;
     }
 
+    /**
+     * Get alias paths.
+     *
+     * @return array<string>
+     */
+    public function getAliasPaths(): array
+    {
+        return $this->aliasPaths;
+    }
+
+    /**
+     * Get alias methods.
+     *
+     * @return array<string>
+     */
+    public function getAliasMethods(): array
+    {
+        return $this->aliasMethods;
+    }
+
     /**
      * Set path param.
      */
diff --git a/src/Http/Router.php b/src/Http/Router.php
@@ -95,19 +95,53 @@ public static function addRoute(Route $route): void
      *
      * @throws \Exception
      */
-    public static function addRouteAlias(string $path, Route $route): void
+    public static function addRouteAlias(string $path, Route $route, ?string $method = null): void
     {
+        $method ??= $route->getMethod();
+
+        if (!\array_key_exists($method, self::$routes)) {
+            throw new Exception("Method ({$method}) not supported.");
+        }
+
         [$alias, $params] = self::preparePath($path);
 
-        if (\array_key_exists($alias, self::$routes[$route->getMethod()]) && !self::$allowOverride) {
-            throw new Exception("Route for ({$route->getMethod()}:{$alias}) already registered.");
+        if (\array_key_exists($alias, self::$routes[$method]) && !self::$allowOverride) {
+            throw new Exception("Route for ({$method}:{$alias}) already registered.");
         }
 
         foreach ($params as $key => $index) {
             $route->setPathParam($key, $index, $alias);
         }
 
-        self::$routes[$route->getMethod()][$alias] = $route;
+        self::$routes[$method][$alias] = $route;
+    }
+
+    /**
+     * Register a route under an additional HTTP method, using its own path.
+     *
+     * @throws \Exception
+     */
+    public static function addRouteMethodAlias(string $method, Route $route): void
+    {
+        if (!\array_key_exists($method, self::$routes)) {
+            throw new Exception("Method ({$method}) not supported.");
+        }
+
+        if ($route->getPath() === '') {
+            throw new Exception('Method aliases are not supported for the wildcard route.');
+        }
+
+        [$path, $params] = self::preparePath($route->getPath());
+
+        if (\array_key_exists($path, self::$routes[$method]) && !self::$allowOverride) {
+            throw new Exception("Route for ({$method}:{$path}) already registered.");
+        }
+
+        foreach ($params as $key => $index) {
+            $route->setPathParam($key, $index, $path);
+        }
+
+        self::$routes[$method][$path] = $route;
     }
 
     /**
diff --git a/tests/HttpTest.php b/tests/HttpTest.php
@@ -250,6 +250,32 @@ public function testCanExecuteRoute(): void
         $this->assertSame('init-' . $resource . '-(init-homepage)-param-x*param-y-(shutdown-homepage)-shutdown', $result);
     }
 
+    public function testCanExecuteRouteWithMethodAlias(): void
+    {
+        $route = Http::get('/v1/oauth/userinfo');
+
+        $route
+            ->aliasMethod(Http::REQUEST_METHOD_POST)
+            ->inject('request')
+            ->action(function ($request) {
+                echo 'userinfo:' . $request->getMethod();
+            });
+
+        $_SERVER['REQUEST_URI'] = '/v1/oauth/userinfo';
+
+        $_SERVER['REQUEST_METHOD'] = 'GET';
+        ob_start();
+        $this->http->run(new Request(), new Response());
+        $result = ob_get_clean();
+        $this->assertSame('userinfo:GET', $result);
+
+        $_SERVER['REQUEST_METHOD'] = 'POST';
+        ob_start();
+        $this->http->run(new Request(), new Response());
+        $result = ob_get_clean();
+        $this->assertSame('userinfo:POST', $result);
+    }
+
     public function testCanAddAndExecuteHooks(): void
     {
         Http::setAllowOverride(true);
diff --git a/tests/RouterTest.php b/tests/RouterTest.php
@@ -8,6 +8,11 @@
 
 final class RouterTest extends TestCase
 {
+    public function setUp(): void
+    {
+        Router::setAllowOverride(false);
+    }
+
     public function tearDown(): void
     {
         Router::reset();
@@ -137,6 +142,104 @@ public function testCanMatchMix(): void
         $this->assertEquals($routeGET, Router::match(Http::REQUEST_METHOD_GET, '/register/lorem/ipsum')?->route);
     }
 
+    public function testCanMatchMethodAlias(): void
+    {
+        $route = new Route(Http::REQUEST_METHOD_GET, '/userinfo');
+        $route->aliasMethod(Http::REQUEST_METHOD_POST);
+
+        Router::addRoute($route);
+
+        $this->assertEquals($route, Router::match(Http::REQUEST_METHOD_GET, '/userinfo')?->route);
+        $this->assertEquals($route, Router::match(Http::REQUEST_METHOD_POST, '/userinfo')?->route);
+        $this->assertNull(Router::match(Http::REQUEST_METHOD_PUT, '/userinfo'));
+
+        $this->assertSame(Http::REQUEST_METHOD_GET, $route->getMethod());
+        $this->assertSame([Http::REQUEST_METHOD_POST], $route->getAliasMethods());
+    }
+
+    public function testCanMatchMethodAliasWithPlaceholder(): void
+    {
+        $route = new Route(Http::REQUEST_METHOD_GET, '/users/:id');
+        $route->aliasMethod(Http::REQUEST_METHOD_POST);
+
+        Router::addRoute($route);
+
+        $match = Router::match(Http::REQUEST_METHOD_POST, '/users/abc-123');
+
+        $this->assertEquals($route, $match?->route);
+        $this->assertSame(['id' => 'abc-123'], $match?->params);
+    }
+
+    public function testMethodAliasCrossesPathAliasesRegardlessOfOrder(): void
+    {
+        $routeA = new Route(Http::REQUEST_METHOD_GET, '/a');
+        $routeA
+            ->alias('/a-old')
+            ->aliasMethod(Http::REQUEST_METHOD_POST);
+
+        Router::addRoute($routeA);
+
+        $routeB = new Route(Http::REQUEST_METHOD_GET, '/b');
+        $routeB
+            ->aliasMethod(Http::REQUEST_METHOD_POST)
+            ->alias('/b-old');
+
+        Router::addRoute($routeB);
+
+        $this->assertEquals($routeA, Router::match(Http::REQUEST_METHOD_POST, '/a')?->route);
+        $this->assertEquals($routeA, Router::match(Http::REQUEST_METHOD_POST, '/a-old')?->route);
+        $this->assertEquals($routeB, Router::match(Http::REQUEST_METHOD_POST, '/b')?->route);
+        $this->assertEquals($routeB, Router::match(Http::REQUEST_METHOD_POST, '/b-old')?->route);
+    }
+
+    public function testCannotRegisterDuplicateMethodAlias(): void
+    {
+        $routePOST = new Route(Http::REQUEST_METHOD_POST, '/userinfo');
+        Router::addRoute($routePOST);
+
+        $routeGET = new Route(Http::REQUEST_METHOD_GET, '/userinfo');
+
+        $this->expectException(\Exception::class);
+        $this->expectExceptionMessage('Route for (POST:userinfo) already registered.');
+        $routeGET->aliasMethod(Http::REQUEST_METHOD_POST);
+    }
+
+    public function testCanOverrideMethodAlias(): void
+    {
+        Router::setAllowOverride(true);
+
+        try {
+            $routePOST = new Route(Http::REQUEST_METHOD_POST, '/userinfo');
+            Router::addRoute($routePOST);
+
+            $routeGET = new Route(Http::REQUEST_METHOD_GET, '/userinfo');
+            Router::addRoute($routeGET);
+            $routeGET->aliasMethod(Http::REQUEST_METHOD_POST);
+
+            $this->assertEquals($routeGET, Router::match(Http::REQUEST_METHOD_POST, '/userinfo')?->route);
+        } finally {
+            Router::setAllowOverride(false);
+        }
+    }
+
+    public function testCannotRegisterMethodAliasForUnknownMethod(): void
+    {
+        $route = new Route(Http::REQUEST_METHOD_GET, '/userinfo');
+
+        $this->expectException(\Exception::class);
+        $this->expectExceptionMessage('Method (TRACE) not supported.');
+        $route->aliasMethod('TRACE');
+    }
+
+    public function testCannotRegisterMethodAliasOnWildcardRoute(): void
+    {
+        $route = new Route('', '');
+
+        $this->expectException(\Exception::class);
+        $this->expectExceptionMessage('Method aliases are not supported for the wildcard route.');
+        $route->aliasMethod(Http::REQUEST_METHOD_POST);
+    }
+
     public function testCanMatchFilename(): void
     {
         $routeGET = new Route(Http::REQUEST_METHOD_GET, '/robots.txt');
