Add HTTP multi-method routes API (#1)

* Add HTTP multi-method routes API

* Simplify HTTP route alias registration

Author: ChiragAgg5k

README.md

@@ -146,6 +146,36 @@ 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.
 
+### Multiple Methods
+
+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:
+
+```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 `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::routes([Http::REQUEST_METHOD_GET, Http::REQUEST_METHOD_POST], '/oauth/userinfo')
+    ->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 aliases and multiple methods combine: a route with both responds on every method under every path. Use `getMethods()` to inspect the methods a route was registered with, and use the request resource to tell how a request arrived.
+
 ### Hooks
 
 There are three types of 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,37 @@ 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.');
+        }
+
+        $routes = Router::getRoutes();
+
+        foreach ($methods as $method) {
+            if (!\array_key_exists($method, $routes)) {
+                throw new \Exception("Method ({$method}) not supported.");
+            }
+        }
+
+        $route = new Route($methods, $url);
+        Router::addRoute($route);
+
+        return $route;
     }
 
     /**

src/Http/Route.php

@@ -7,9 +7,11 @@
 class Route extends Hook
 {
     /**
-     * HTTP Method
+     * HTTP Methods
+     *
+     * @var array<string>
      */
-    protected string $method = '';
+    protected array $methods = [];
 
     /**
      * Whether to use hook
@@ -28,6 +30,13 @@ class Route extends Hook
      */
     protected array $pathParams = [];
 
+    /**
+     * Alias paths this route is also registered under.
+     *
+     * @var array<string>
+     */
+    protected array $aliasPaths = [];
+
     /**
      * Internal counter.
      */
@@ -38,11 +47,14 @@ class Route extends Hook
      */
     protected int $order;
 
-    public function __construct(string $method, string $path)
+    /**
+     * @param string|array<int, string> $methods
+     */
+    public function __construct(string|array $methods, string $path)
     {
         parent::__construct();
         $this->path($path);
-        $this->method = $method;
+        $this->methods = \is_array($methods) ? array_values(array_unique($methods)) : [$methods];
         $this->order = ++self::$counter;
     }
 
@@ -71,6 +83,10 @@ public function alias(string $path): self
     {
         Router::addRouteAlias($path, $this);
 
+        if (!\in_array($path, $this->aliasPaths, true)) {
+            $this->aliasPaths[] = $path;
+        }
+
         return $this;
     }
 
@@ -85,11 +101,13 @@ public function hook(bool $hook = true): self
     }
 
     /**
-     * Get HTTP Method
+     * Get primary HTTP method.
+     *
+     * @deprecated Use getMethods() instead.
      */
     public function getMethod(): string
     {
-        return $this->method;
+        return $this->methods[0] ?? '';
     }
 
     /**
@@ -108,6 +126,16 @@ public function getHook(): bool
         return $this->hook;
     }
 
+    /**
+     * Get HTTP methods this route is registered under.
+     *
+     * @return array<string>
+     */
+    public function getMethods(): array
+    {
+        return $this->methods;
+    }
+
     /**
      * Set path param.
      */

src/Http/Router.php

@@ -74,20 +74,41 @@ public static function setAllowOverride(bool $value): void
     public static function addRoute(Route $route): void
     {
         [$path, $params] = self::preparePath($route->getPath());
+        $methods = $route->getMethods();
+        $method = $methods[0] ?? '';
+        $additionalMethods = \array_slice($methods, 1);
 
-        if (!\array_key_exists($route->getMethod(), self::$routes)) {
-            throw new Exception("Method ({$route->getMethod()}) not supported.");
+        if (!\array_key_exists($method, self::$routes)) {
+            throw new Exception("Method ({$method}) not supported.");
+        }
+
+        if (\array_key_exists($path, self::$routes[$method]) && !self::$allowOverride) {
+            throw new Exception("Route for ({$method}:{$path}) already registered.");
         }
 
-        if (\array_key_exists($path, self::$routes[$route->getMethod()]) && !self::$allowOverride) {
-            throw new Exception("Route for ({$route->getMethod()}:{$path}) already registered.");
+        foreach ($additionalMethods as $additionalMethod) {
+            if (!\array_key_exists($additionalMethod, self::$routes)) {
+                throw new Exception("Method ({$additionalMethod}) not supported.");
+            }
+
+            if ($route->getPath() === '') {
+                throw new Exception('Additional route methods are not supported for the wildcard route.');
+            }
+
+            if (\array_key_exists($path, self::$routes[$additionalMethod]) && !self::$allowOverride) {
+                throw new Exception("Route for ({$additionalMethod}:{$path}) already registered.");
+            }
         }
 
         foreach ($params as $key => $index) {
             $route->setPathParam($key, $index, $path);
         }
 
-        self::$routes[$route->getMethod()][$path] = $route;
+        self::$routes[$method][$path] = $route;
+
+        foreach ($additionalMethods as $additionalMethod) {
+            self::$routes[$additionalMethod][$path] = $route;
+        }
     }
 
     /**
@@ -97,17 +118,26 @@ public static function addRoute(Route $route): void
      */
     public static function addRouteAlias(string $path, Route $route): void
     {
+        $methods = $route->getMethods();
         [$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.");
+        foreach ($methods as $method) {
+            if (!\array_key_exists($method, self::$routes)) {
+                throw new Exception("Method ({$method}) not supported.");
+            }
+
+            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;
+        foreach ($methods as $method) {
+            self::$routes[$method][$alias] = $route;
+        }
     }
 
     /**
@@ -232,6 +262,7 @@ public static function reset(): void
     {
         self::$params = [];
         self::$wildcard = null;
+        self::$allowOverride = false;
         self::$routes = [
             Http::REQUEST_METHOD_GET => [],
             Http::REQUEST_METHOD_POST => [],

tests/HttpTest.php

@@ -250,6 +250,29 @@ public function testCanExecuteRoute(): void
         $this->assertSame('init-' . $resource . '-(init-homepage)-param-x*param-y-(shutdown-homepage)-shutdown', $result);
     }
 
+    public function testCanExecuteRouteWithMultipleMethods(): void
+    {
+        Http::routes([Http::REQUEST_METHOD_GET, Http::REQUEST_METHOD_POST], '/v1/oauth/userinfo')
+            ->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);

tests/RouteTest.php

@@ -19,6 +19,7 @@ public function setUp(): void
     public function testCanGetMethod(): void
     {
         $this->assertSame('GET', $this->route->getMethod());
+        $this->assertSame(['GET'], $this->route->getMethods());
     }
 
     public function testCanGetAndSetPath(): void