Refactor route method aliases to routes API

Author: ChiragAgg5k

README.md

@@ -143,9 +143,9 @@ 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
+### Aliases and Multiple Methods
 
-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.
+A route can be registered under additional paths and multiple HTTP methods. All matching paths and methods 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:
 
@@ -159,11 +159,10 @@ Http::get('/users/: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:
+Use `routes()` to serve the same route under multiple HTTP methods. For example, the OpenID Connect UserInfo endpoint must support both GET and POST:
 
 ```php
-Http::get('/oauth/userinfo')
-    ->aliasMethod(Http::REQUEST_METHOD_POST)
+Http::routes([Http::REQUEST_METHOD_GET, Http::REQUEST_METHOD_POST], '/oauth/userinfo')
     ->inject('request')
     ->inject('response')
     ->action(function(Request $request, Response $response) {
@@ -172,7 +171,7 @@ Http::get('/oauth/userinfo')
     });
 ```
 
-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.
+Path aliases and multiple methods combine: a route with both responds on every method under every path. Note that `getMethod()` on the route returns the first method it was defined with; use the request resource to tell how a request arrived.
 
 ### Hooks
 

src/Http/Http.php

@@ -179,7 +179,7 @@ public function setCompressionSupported(mixed $compressionSupported): void
      */
     public static function get(string $url): Route
     {
-        return self::addRoute(self::REQUEST_METHOD_GET, $url);
+        return self::routes(self::REQUEST_METHOD_GET, $url);
     }
 
     /**
@@ -189,7 +189,7 @@ public static function get(string $url): Route
      */
     public static function post(string $url): Route
     {
-        return self::addRoute(self::REQUEST_METHOD_POST, $url);
+        return self::routes(self::REQUEST_METHOD_POST, $url);
     }
 
     /**
@@ -199,7 +199,7 @@ public static function post(string $url): Route
      */
     public static function put(string $url): Route
     {
-        return self::addRoute(self::REQUEST_METHOD_PUT, $url);
+        return self::routes(self::REQUEST_METHOD_PUT, $url);
     }
 
     /**
@@ -209,7 +209,7 @@ public static function put(string $url): Route
      */
     public static function patch(string $url): Route
     {
-        return self::addRoute(self::REQUEST_METHOD_PATCH, $url);
+        return self::routes(self::REQUEST_METHOD_PATCH, $url);
     }
 
     /**
@@ -219,7 +219,29 @@ public static function patch(string $url): Route
      */
     public static function delete(string $url): Route
     {
-        return self::addRoute(self::REQUEST_METHOD_DELETE, $url);
+        return self::routes(self::REQUEST_METHOD_DELETE, $url);
+    }
+
+    /**
+     * ROUTES
+     *
+     * Add one route under one or more request methods
+     *
+     * @param string|array<int, string> $methods
+     */
+    public static function routes(string|array $methods, string $url): Route
+    {
+        $methods = \is_array($methods) ? $methods : [$methods];
+        $methods = array_values(array_unique($methods));
+
+        if (empty($methods)) {
+            throw new \Exception('At least one HTTP method is required.');
+        }
+
+        $route = new Route($methods[0], $url, \array_slice($methods, 1));
+        Router::addRoute($route);
+
+        return $route;
     }
 
     /**

src/Http/Route.php

@@ -36,11 +36,11 @@ class Route extends Hook
     protected array $aliasPaths = [];
 
     /**
-     * Alias HTTP methods this route is also registered under.
+     * Additional HTTP methods this route is also registered under.
      *
      * @var array<string>
      */
-    protected array $aliasMethods = [];
+    protected array $additionalMethods = [];
 
     /**
      * Internal counter.
@@ -52,11 +52,15 @@ class Route extends Hook
      */
     protected int $order;
 
-    public function __construct(string $method, string $path)
+    /**
+     * @param array<int, string> $additionalMethods
+     */
+    public function __construct(string $method, string $path, array $additionalMethods = [])
     {
         parent::__construct();
         $this->path($path);
         $this->method = $method;
+        $this->additionalMethods = $additionalMethods;
         $this->order = ++self::$counter;
     }
 
@@ -85,7 +89,7 @@ public function alias(string $path): self
     {
         Router::addRouteAlias($path, $this);
 
-        foreach ($this->aliasMethods as $method) {
+        foreach ($this->additionalMethods as $method) {
             Router::addRouteAlias($path, $this, $method);
         }
 
@@ -96,27 +100,6 @@ public function alias(string $path): self
         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);
-        }
-
-        if (!\in_array($method, $this->aliasMethods, true)) {
-            $this->aliasMethods[] = $method;
-        }
-
-        return $this;
-    }
-
     /**
      * When set false, hooks for this route will be skipped.
      */
@@ -162,13 +145,13 @@ public function getAliasPaths(): array
     }
 
     /**
-     * Get alias methods.
+     * Get methods this route is registered under.
      *
      * @return array<string>
      */
-    public function getAliasMethods(): array
+    public function getMethods(): array
     {
-        return $this->aliasMethods;
+        return array_merge([$this->method], $this->additionalMethods);
     }
 
     /**

src/Http/Router.php

@@ -88,6 +88,10 @@ public static function addRoute(Route $route): void
         }
 
         self::$routes[$route->getMethod()][$path] = $route;
+
+        foreach (\array_slice($route->getMethods(), 1) as $method) {
+            self::addRouteMethod($method, $route);
+        }
     }
 
     /**
@@ -121,14 +125,14 @@ public static function addRouteAlias(string $path, Route $route, ?string $method
      *
      * @throws \Exception
      */
-    public static function addRouteMethodAlias(string $method, Route $route): void
+    public static function addRouteMethod(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.');
+            throw new Exception('Additional route methods are not supported for the wildcard route.');
         }
 
         [$path, $params] = self::preparePath($route->getPath());

tests/HttpTest.php

@@ -250,12 +250,9 @@ public function testCanExecuteRoute(): void
         $this->assertSame('init-' . $resource . '-(init-homepage)-param-x*param-y-(shutdown-homepage)-shutdown', $result);
     }
 
-    public function testCanExecuteRouteWithMethodAlias(): void
+    public function testCanExecuteRouteWithMultipleMethods(): void
     {
-        $route = Http::get('/v1/oauth/userinfo');
-
-        $route
-            ->aliasMethod(Http::REQUEST_METHOD_POST)
+        Http::routes([Http::REQUEST_METHOD_GET, Http::REQUEST_METHOD_POST], '/v1/oauth/userinfo')
             ->inject('request')
             ->action(function ($request) {
                 echo 'userinfo:' . $request->getMethod();

tests/RouterTest.php

@@ -142,104 +142,91 @@ public function testCanMatchMix(): void
         $this->assertEquals($routeGET, Router::match(Http::REQUEST_METHOD_GET, '/register/lorem/ipsum')?->route);
     }
 
-    public function testCanMatchMethodAlias(): void
+    public function testCanMatchRouteWithMultipleMethods(): void
     {
-        $route = new Route(Http::REQUEST_METHOD_GET, '/userinfo');
-        $route->aliasMethod(Http::REQUEST_METHOD_POST);
-
-        Router::addRoute($route);
+        $route = Http::routes([Http::REQUEST_METHOD_GET, Http::REQUEST_METHOD_POST], '/userinfo');
 
         $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());
+        $this->assertSame([Http::REQUEST_METHOD_GET, Http::REQUEST_METHOD_POST], $route->getMethods());
     }
 
-    public function testCanMatchMethodAliasWithPlaceholder(): void
+    public function testCanMatchRouteWithStringMethod(): void
     {
-        $route = new Route(Http::REQUEST_METHOD_GET, '/users/:id');
-        $route->aliasMethod(Http::REQUEST_METHOD_POST);
+        $route = Http::routes(Http::REQUEST_METHOD_GET, '/userinfo');
 
-        Router::addRoute($route);
+        $this->assertEquals($route, Router::match(Http::REQUEST_METHOD_GET, '/userinfo')?->route);
+        $this->assertNull(Router::match(Http::REQUEST_METHOD_POST, '/userinfo'));
+        $this->assertSame([Http::REQUEST_METHOD_GET], $route->getMethods());
+    }
+
+    public function testCanMatchRouteWithMultipleMethodsAndPlaceholder(): void
+    {
+        $route = Http::routes([Http::REQUEST_METHOD_GET, Http::REQUEST_METHOD_POST], '/users/:id');
 
         $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
+    public function testRoutesCrossPathAliases(): void
     {
-        $routeA = new Route(Http::REQUEST_METHOD_GET, '/a');
-        $routeA
-            ->alias('/a-old')
-            ->aliasMethod(Http::REQUEST_METHOD_POST);
+        $route = Http::routes([Http::REQUEST_METHOD_GET, Http::REQUEST_METHOD_POST], '/a')
+            ->alias('/a-old');
 
-        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);
+        $this->assertEquals($route, Router::match(Http::REQUEST_METHOD_GET, '/a')?->route);
+        $this->assertEquals($route, Router::match(Http::REQUEST_METHOD_POST, '/a')?->route);
+        $this->assertEquals($route, Router::match(Http::REQUEST_METHOD_GET, '/a-old')?->route);
+        $this->assertEquals($route, Router::match(Http::REQUEST_METHOD_POST, '/a-old')?->route);
     }
 
-    public function testCannotRegisterDuplicateMethodAlias(): void
+    public function testCannotRegisterDuplicateRouteMethod(): 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);
+        Http::routes([Http::REQUEST_METHOD_GET, Http::REQUEST_METHOD_POST], '/userinfo');
     }
 
-    public function testCanOverrideMethodAlias(): void
+    public function testCanOverrideRouteMethod(): 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);
-            $routeGET->aliasMethod(Http::REQUEST_METHOD_POST);
+            $routeGET = Http::routes([
+                Http::REQUEST_METHOD_GET,
+                Http::REQUEST_METHOD_POST,
+                Http::REQUEST_METHOD_POST,
+            ], '/userinfo');
 
             $this->assertEquals($routeGET, Router::match(Http::REQUEST_METHOD_POST, '/userinfo')?->route);
-            $this->assertSame([Http::REQUEST_METHOD_POST], $routeGET->getAliasMethods());
+            $this->assertSame([Http::REQUEST_METHOD_GET, Http::REQUEST_METHOD_POST], $routeGET->getMethods());
         } finally {
             Router::setAllowOverride(false);
         }
     }
 
-    public function testCannotRegisterMethodAliasForUnknownMethod(): void
+    public function testCannotRegisterRouteForUnknownMethod(): void
     {
-        $route = new Route(Http::REQUEST_METHOD_GET, '/userinfo');
-
         $this->expectException(\Exception::class);
         $this->expectExceptionMessage('Method (TRACE) not supported.');
-        $route->aliasMethod('TRACE');
+        Http::routes([Http::REQUEST_METHOD_GET, 'TRACE'], '/userinfo');
     }
 
-    public function testCannotRegisterMethodAliasOnWildcardRoute(): void
+    public function testCannotRegisterRouteWithoutMethods(): 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);
+        $this->expectExceptionMessage('At least one HTTP method is required.');
+        Http::routes([], '/userinfo');
     }
 
     public function testCanMatchFilename(): void