feat(router): throw exception when generating an uri to a controller action that has multiple different routes

Author: innocenzi

packages/router/src/Exceptions/ControllerMethodHasMultipleRoutes.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Router\Exceptions;
+
+use Exception;
+use Tempest\Support\Arr;
+
+final class ControllerMethodHasMultipleRoutes extends Exception implements RouterException
+{
+    /** @param string[] $routes */
+    public function __construct(string $controllerClass, string $controllerMethod, array $routes)
+    {
+        parent::__construct(vsprintf(
+            format: "Controller method `%s::%s()` has multiple different routes: \"%s\". Please use the route path directly.",
+            values: [
+                $controllerClass,
+                $controllerMethod,
+                Arr\join($routes),
+            ],
+        ));
+    }
+}

packages/router/src/RouteConfig.php

@@ -18,7 +18,7 @@ public function __construct(
         /** @var array<string,\Tempest\Router\Routing\Matching\MatchingRegex> */
         public array $matchingRegexes = [],
 
-        /** @var array<string,string> */
+        /** @var array<string,string[]> */
         public array $handlerIndex = [],
 
         /** @var class-string<\Tempest\Router\ResponseProcessor>[] */

packages/router/src/Routing/Construction/RouteConfigurator.php

@@ -37,7 +37,10 @@ public function __construct()
     public function addRoute(DiscoveredRoute $route): void
     {
         $this->isDirty = true;
-        $this->handlerIndex[$route->handler->getDeclaringClass()->getName() . '::' . $route->handler->getName()] = $route->uri;
+
+        $handler = $route->handler->getDeclaringClass()->getName() . '::' . $route->handler->getName();
+        $this->handlerIndex[$handler] ??= [];
+        $this->handlerIndex[$handler][] = $route->uri;
 
         if ($route->isDynamic) {
             $this->addDynamicRoute($route);

packages/router/src/UriGenerator.php

@@ -15,6 +15,7 @@
 use Tempest\Reflection\MethodReflector;
 use Tempest\Router\Exceptions\ControllerActionDoesNotExist;
 use Tempest\Router\Exceptions\ControllerMethodHadNoRoute;
+use Tempest\Router\Exceptions\ControllerMethodHasMultipleRoutes;
 use Tempest\Router\Routing\Construction\DiscoveredRoute;
 use Tempest\Support\Arr;
 use Tempest\Support\Regex;
@@ -208,9 +209,9 @@ private function normalizeActionToUri(array|string|MethodReflector $action): str
 
         [$controllerClass, $controllerMethod] = is_array($action) ? $action : [$action, '__invoke'];
 
-        $uri = $this->routeConfig->handlerIndex[$controllerClass . '::' . $controllerMethod] ?? null;
+        $routes = array_unique($this->routeConfig->handlerIndex[$controllerClass . '::' . $controllerMethod] ?? []);
 
-        if (! $uri) {
+        if ($routes === []) {
             if (! class_exists($controllerClass)) {
                 throw ControllerActionDoesNotExist::controllerNotFound($controllerClass, $controllerMethod);
             }
@@ -222,6 +223,10 @@ private function normalizeActionToUri(array|string|MethodReflector $action): str
             throw new ControllerMethodHadNoRoute($controllerClass, $controllerMethod);
         }
 
-        return Str\ensure_starts_with($uri, '/');
+        if (count($routes) > 1) {
+            throw new ControllerMethodHasMultipleRoutes($controllerClass, $controllerMethod, $routes);
+        }
+
+        return Str\ensure_starts_with($routes[0], '/');
     }
 }

tests/Fixtures/Controllers/ControllerWithRepeatedRoutes.php

@@ -17,6 +17,7 @@
     #[Get('/repeated/d')]
     #[Post('/repeated/e')]
     #[Post('/repeated/f')]
+    #[Get('/repeated/f')]
     public function __invoke(): Response
     {
         return new Ok();

tests/Integration/Route/UriGeneratorTest.php

@@ -10,8 +10,10 @@
 use Tempest\Http\GenericRequest;
 use Tempest\Http\Method;
 use Tempest\Router\Exceptions\ControllerActionDoesNotExist;
+use Tempest\Router\Exceptions\ControllerMethodHasMultipleRoutes;
 use Tempest\Router\UriGenerator;
 use Tests\Tempest\Fixtures\Controllers\ControllerWithEnumBinding;
+use Tests\Tempest\Fixtures\Controllers\ControllerWithRepeatedRoutes;
 use Tests\Tempest\Fixtures\Controllers\EnumForController;
 use Tests\Tempest\Fixtures\Controllers\PrefixController;
 use Tests\Tempest\Fixtures\Controllers\TestController;
@@ -282,4 +284,22 @@ public function is_current_uri_with_prefix_decorator(): void
 
         $this->assertTrue($this->generator->isCurrentUri(PrefixController::class));
     }
+
+    #[Test]
+    public function controller_with_multiple_routes(): void
+    {
+        $this->expectException(ControllerMethodHasMultipleRoutes::class);
+        $this->expectExceptionMessage('Controller method `' . ControllerWithRepeatedRoutes::class . '::__invoke()` has multiple different routes');
+
+        $this->generator->createUri(ControllerWithRepeatedRoutes::class);
+    }
+
+    #[Test]
+    public function uri_to_controller_with_multiple_routes(): void
+    {
+        $this->assertSame(
+            '/repeated/a',
+            $this->generator->createUri('/repeated/a'),
+        );
+    }
 }