Implement extra parameters

This introduces the possibility of providing extra parameters during route registration (such as route name) and by default registers the unparsed route an item on the list. Signed-off-by: Luís Cobucci <[email protected]>
nikic · Jan 31, 2024 · 240543d · 240543d
1 parent 53d13c1
commit 240543d
Show file tree

Hide file tree

Showing 17 changed files with 178 additions and 114 deletions.
diff --git a/src/DataGenerator.php b/src/DataGenerator.php
@@ -4,8 +4,9 @@
 namespace FastRoute;
 
 /**
- * @phpstan-type StaticRoutes array<string, array<string, mixed>>
- * @phpstan-type DynamicRouteChunk array{regex: string, suffix?: string, routeMap: array<int|string, array{mixed, array<string, string>}>}
+ * @phpstan-type ExtraParameters array<string, string|int|bool|float>
+ * @phpstan-type StaticRoutes array<string, array<string, array{mixed, ExtraParameters}>>
+ * @phpstan-type DynamicRouteChunk array{regex: string, suffix?: string, routeMap: array<int|string, array{mixed, array<string, string>, ExtraParameters}>}
  * @phpstan-type DynamicRouteChunks list<DynamicRouteChunk>
  * @phpstan-type DynamicRoutes array<string, DynamicRouteChunks>
  * @phpstan-type RouteData array{StaticRoutes, DynamicRoutes}
@@ -21,8 +22,9 @@ interface DataGenerator
      * matches.
      *
      * @param array<string|array{0: string, 1:string}> $routeData
+     * @param ExtraParameters                          $extraParameters
      */
-    public function addRoute(string $httpMethod, array $routeData, mixed $handler): void;
+    public function addRoute(string $httpMethod, array $routeData, mixed $handler, array $extraParameters = []): void;
 
     /**
      * Returns dispatcher data in some unspecified format, which

diff --git a/src/DataGenerator/CharCountBased.php b/src/DataGenerator/CharCountBased.php
@@ -27,7 +27,7 @@ protected function processChunk(array $regexToRoutesMap): array
             $suffix .= "\t";
 
             $regexes[] = '(?:' . $regex . '/(\t{' . $suffixLen . '})\t{' . ($count - $suffixLen) . '})';
-            $routeMap[$suffix] = [$route->handler, $route->variables];
+            $routeMap[$suffix] = [$route->handler, $route->variables, $route->extraParameters];
         }
 
         $regex = '~^(?|' . implode('|', $regexes) . ')$~';

diff --git a/src/DataGenerator/GroupCountBased.php b/src/DataGenerator/GroupCountBased.php
@@ -26,7 +26,7 @@ protected function processChunk(array $regexToRoutesMap): array
             $numGroups = max($numGroups, $numVariables);
 
             $regexes[] = $regex . str_repeat('()', $numGroups - $numVariables);
-            $routeMap[$numGroups + 1] = [$route->handler, $route->variables];
+            $routeMap[$numGroups + 1] = [$route->handler, $route->variables, $route->extraParameters];
 
             ++$numGroups;
         }

diff --git a/src/DataGenerator/GroupPosBased.php b/src/DataGenerator/GroupPosBased.php
@@ -21,7 +21,7 @@ protected function processChunk(array $regexToRoutesMap): array
         $offset = 1;
         foreach ($regexToRoutesMap as $regex => $route) {
             $regexes[] = $regex;
-            $routeMap[$offset] = [$route->handler, $route->variables];
+            $routeMap[$offset] = [$route->handler, $route->variables, $route->extraParameters];
 
             $offset += count($route->variables);
         }

diff --git a/src/DataGenerator/MarkBased.php b/src/DataGenerator/MarkBased.php
@@ -21,7 +21,7 @@ protected function processChunk(array $regexToRoutesMap): array
 
         foreach ($regexToRoutesMap as $regex => $route) {
             $regexes[] = $regex . '(*MARK:' . $markName . ')';
-            $routeMap[$markName] = [$route->handler, $route->variables];
+            $routeMap[$markName] = [$route->handler, $route->variables, $route->extraParameters];
 
             ++$markName;
         }

diff --git a/src/DataGenerator/RegexBasedAbstract.php b/src/DataGenerator/RegexBasedAbstract.php
@@ -21,6 +21,7 @@
  * @phpstan-import-type DynamicRouteChunk from DataGenerator
  * @phpstan-import-type DynamicRoutes from DataGenerator
  * @phpstan-import-type RouteData from DataGenerator
+ * @phpstan-import-type ExtraParameters from DataGenerator
  */
 abstract class RegexBasedAbstract implements DataGenerator
 {
@@ -40,12 +41,12 @@ abstract protected function getApproxChunkSize(): int;
     abstract protected function processChunk(array $regexToRoutesMap): array;
 
     /** @inheritDoc */
-    public function addRoute(string $httpMethod, array $routeData, mixed $handler): void
+    public function addRoute(string $httpMethod, array $routeData, mixed $handler, array $extraParameters = []): void
     {
         if ($this->isStaticRoute($routeData)) {
-            $this->addStaticRoute($httpMethod, $routeData, $handler);
+            $this->addStaticRoute($httpMethod, $routeData, $handler, $extraParameters);
         } else {
-            $this->addVariableRoute($httpMethod, $routeData, $handler);
+            $this->addVariableRoute($httpMethod, $routeData, $handler, $extraParameters);
         }
     }
 
@@ -88,8 +89,11 @@ private function isStaticRoute(array $routeData): bool
         return count($routeData) === 1 && is_string($routeData[0]);
     }
 
-    /** @param array<string|array{0: string, 1:string}> $routeData */
-    private function addStaticRoute(string $httpMethod, array $routeData, mixed $handler): void
+    /**
+     * @param array<string|array{0: string, 1:string}> $routeData
+     * @param ExtraParameters                          $extraParameters
+     */
+    private function addStaticRoute(string $httpMethod, array $routeData, mixed $handler, array $extraParameters): void
     {
         $routeStr = $routeData[0];
         assert(is_string($routeStr));
@@ -106,13 +110,16 @@ private function addStaticRoute(string $httpMethod, array $routeData, mixed $han
             }
         }
 
-        $this->staticRoutes[$httpMethod][$routeStr] = $handler;
+        $this->staticRoutes[$httpMethod][$routeStr] = [$handler, $extraParameters];
     }
 
-    /** @param array<string|array{0: string, 1:string}> $routeData */
-    private function addVariableRoute(string $httpMethod, array $routeData, mixed $handler): void
+    /**
+     * @param array<string|array{0: string, 1:string}> $routeData
+     * @param ExtraParameters                          $extraParameters
+     */
+    private function addVariableRoute(string $httpMethod, array $routeData, mixed $handler, array $extraParameters): void
     {
-        $route = Route::fromParsedRoute($httpMethod, $routeData, $handler);
+        $route = Route::fromParsedRoute($httpMethod, $routeData, $handler, $extraParameters);
         $regex = $route->regex;
 
         if (isset($this->methodToRegexToRoutesMap[$httpMethod][$regex])) {

diff --git a/src/Dispatcher/CharCountBased.php b/src/Dispatcher/CharCountBased.php
@@ -21,7 +21,7 @@ protected function dispatchVariableRoute(array $routeData, string $uri): ?Matche
                 continue;
             }
 
-            [$handler, $varNames] = $data['routeMap'][end($matches)];
+            [$handler, $varNames, $extraParameters] = $data['routeMap'][end($matches)];
 
             $vars = [];
             $i = 0;
@@ -32,6 +32,7 @@ protected function dispatchVariableRoute(array $routeData, string $uri): ?Matche
             $result = new Matched();
             $result->handler = $handler;
             $result->variables = $vars;
+            $result->extraParameters = $extraParameters;
 
             return $result;
         }

diff --git a/src/Dispatcher/GroupCountBased.php b/src/Dispatcher/GroupCountBased.php
@@ -18,7 +18,7 @@ protected function dispatchVariableRoute(array $routeData, string $uri): ?Matche
                 continue;
             }
 
-            [$handler, $varNames] = $data['routeMap'][count($matches)];
+            [$handler, $varNames, $extraParameters] = $data['routeMap'][count($matches)];
 
             $vars = [];
             $i = 0;
@@ -29,6 +29,7 @@ protected function dispatchVariableRoute(array $routeData, string $uri): ?Matche
             $result = new Matched();
             $result->handler = $handler;
             $result->variables = $vars;
+            $result->extraParameters = $extraParameters;
 
             return $result;
         }

diff --git a/src/Dispatcher/GroupPosBased.php b/src/Dispatcher/GroupPosBased.php
@@ -25,7 +25,7 @@ protected function dispatchVariableRoute(array $routeData, string $uri): ?Matche
 
             assert(isset($i));
 
-            [$handler, $varNames] = $data['routeMap'][$i];
+            [$handler, $varNames, $extraParameters] = $data['routeMap'][$i];
 
             $vars = [];
             foreach ($varNames as $varName) {
@@ -35,6 +35,7 @@ protected function dispatchVariableRoute(array $routeData, string $uri): ?Matche
             $result = new Matched();
             $result->handler = $handler;
             $result->variables = $vars;
+            $result->extraParameters = $extraParameters;
 
             return $result;
         }

diff --git a/src/Dispatcher/MarkBased.php b/src/Dispatcher/MarkBased.php
@@ -17,7 +17,7 @@ protected function dispatchVariableRoute(array $routeData, string $uri): ?Matche
                 continue;
             }
 
-            [$handler, $varNames] = $data['routeMap'][$matches['MARK']];
+            [$handler, $varNames, $extraParameters] = $data['routeMap'][$matches['MARK']];
 
             $vars = [];
             $i = 0;
@@ -28,6 +28,7 @@ protected function dispatchVariableRoute(array $routeData, string $uri): ?Matche
             $result = new Matched();
             $result->handler = $handler;
             $result->variables = $vars;
+            $result->extraParameters = $extraParameters;
 
             return $result;
         }

diff --git a/src/Dispatcher/RegexBasedAbstract.php b/src/Dispatcher/RegexBasedAbstract.php
@@ -37,7 +37,8 @@ public function dispatch(string $httpMethod, string $uri): Matched|NotMatched|Me
     {
         if (isset($this->staticRouteMap[$httpMethod][$uri])) {
             $result = new Matched();
-            $result->handler = $this->staticRouteMap[$httpMethod][$uri];
+            $result->handler = $this->staticRouteMap[$httpMethod][$uri][0];
+            $result->extraParameters = $this->staticRouteMap[$httpMethod][$uri][1];
 
             return $result;
         }
@@ -53,7 +54,8 @@ public function dispatch(string $httpMethod, string $uri): Matched|NotMatched|Me
         if ($httpMethod === 'HEAD') {
             if (isset($this->staticRouteMap['GET'][$uri])) {
                 $result = new Matched();
-                $result->handler = $this->staticRouteMap['GET'][$uri];
+                $result->handler = $this->staticRouteMap['GET'][$uri][0];
+                $result->extraParameters = $this->staticRouteMap['GET'][$uri][1];
 
                 return $result;
             }
@@ -69,7 +71,8 @@ public function dispatch(string $httpMethod, string $uri): Matched|NotMatched|Me
         // If nothing else matches, try fallback routes
         if (isset($this->staticRouteMap['*'][$uri])) {
             $result = new Matched();
-            $result->handler = $this->staticRouteMap['*'][$uri];
+            $result->handler = $this->staticRouteMap['*'][$uri][0];
+            $result->extraParameters = $this->staticRouteMap['*'][$uri][1];
 
             return $result;
         }

diff --git a/src/Dispatcher/Result/Matched.php b/src/Dispatcher/Result/Matched.php
@@ -4,11 +4,15 @@
 namespace FastRoute\Dispatcher\Result;
 
 use ArrayAccess;
+use FastRoute\DataGenerator;
 use FastRoute\Dispatcher;
 use OutOfBoundsException;
 use RuntimeException;
 
-/** @implements ArrayAccess<int, Dispatcher::FOUND|mixed|array<string, string>> */
+/**
+ * @phpstan-import-type ExtraParameters from DataGenerator
+ * @implements ArrayAccess<int, Dispatcher::FOUND|mixed|array<string, string>>
+ */
 final class Matched implements ArrayAccess
 {
     /** @readonly */
@@ -20,6 +24,12 @@ final class Matched implements ArrayAccess
      */
     public array $variables = [];
 
+    /**
+     * @readonly
+     * @var ExtraParameters
+     */
+    public array $extraParameters = [];
+
     public function offsetExists(mixed $offset): bool
     {
         return $offset >= 0 && $offset <= 2;

diff --git a/src/Route.php b/src/Route.php
@@ -7,19 +7,27 @@
 use function preg_match;
 use function preg_quote;
 
+/** @phpstan-import-type ExtraParameters from DataGenerator */
 class Route
 {
-    /** @param array<string, string> $variables */
+    /**
+     * @param array<string, string> $variables
+     * @param ExtraParameters       $extraParameters
+     */
     public function __construct(
-        public string $httpMethod,
-        public mixed $handler,
-        public string $regex,
-        public array $variables,
+        public readonly string $httpMethod,
+        public readonly mixed $handler,
+        public readonly string $regex,
+        public readonly array $variables,
+        public readonly array $extraParameters,
     ) {
     }
 
-    /** @param array<string|array{0: string, 1:string}> $routeData */
-    public static function fromParsedRoute(string $httpMethod, array $routeData, mixed $handler): self
+    /**
+     * @param array<string|array{0: string, 1:string}> $routeData
+     * @param ExtraParameters                          $extraParameters
+     */
+    public static function fromParsedRoute(string $httpMethod, array $routeData, mixed $handler, array $extraParameters = []): self
     {
         [$regex, $variables] = self::extractRegex($routeData);
 
@@ -28,6 +36,7 @@ public static function fromParsedRoute(string $httpMethod, array $routeData, mix
             $handler,
             $regex,
             $variables,
+            $extraParameters,
         );
     }