feat: implement optional route parameters

Author: xHeaven

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

@@ -14,6 +14,8 @@ final class DiscoveredRoute implements Route
 
     public const string ROUTE_PARAM_NAME_REGEX = '(\w*)';
 
+    public const string ROUTE_PARAM_OPTIONAL_REGEX = '(\??)';
+
     public const string ROUTE_PARAM_CUSTOM_REGEX = '(?::([^{}]*(?:\{(?-1)\}[^{}]*)*))?';
 
     /** @param \Tempest\Router\RouteDecorator[] $decorators */
@@ -23,10 +25,13 @@ public static function fromRoute(Route $route, array $decorators, MethodReflecto
             $route = $decorator->decorate($route);
         }
 
+        $paramInfo = self::getRouteParams($route->uri);
+
         return new self(
             $route->uri,
             $route->method,
-            self::getRouteParams($route->uri),
+            $paramInfo['names'],
+            $paramInfo['optional'],
             $route->middleware,
             $methodReflector,
             $route->without ?? [],
@@ -39,6 +44,8 @@ private function __construct(
         public string $uri,
         public Method $method,
         public array $parameters,
+        /** @var array<string, bool> */
+        public array $optionalParameters,
         /** @var class-string<\Tempest\Router\HttpMiddleware>[] */
         public array $middleware,
         public MethodReflector $handler,
@@ -47,14 +54,30 @@ private function __construct(
         $this->isDynamic = $parameters !== [];
     }
 
-    /** @return string[] */
+    /**
+     * @return array{
+     *     names: string[],
+     *     optional: array<string, bool>
+     * }
+     */
     private static function getRouteParams(string $uriPart): array
     {
-        $regex = '#\{' . self::ROUTE_PARAM_NAME_REGEX . self::ROUTE_PARAM_CUSTOM_REGEX . '\}#';
+        $regex = '#\{' . self::ROUTE_PARAM_NAME_REGEX . self::ROUTE_PARAM_OPTIONAL_REGEX . self::ROUTE_PARAM_CUSTOM_REGEX . '\}#';
 
         preg_match_all($regex, $uriPart, $matches);
 
-        return $matches[1] ?? [];
+        $names = $matches[1] ?? [];
+        $optionalMarkers = $matches[2] ?? [];
+
+        $optional = [];
+        foreach ($names as $i => $name) {
+            $optional[$name] = $optionalMarkers[$i] === '?';
+        }
+
+        return [
+            'names' => $names,
+            'optional' => $optional,
+        ];
     }
 
     /**

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

@@ -50,22 +50,24 @@ public function findOrCreateNodeForSegment(string $routeSegment): self
         return $this->dynamicPaths[$regexRouteSegment] ??= self::createDynamicRouteNode($regexRouteSegment);
     }
 
-    public function setTargetRoute(MarkedRoute $markedRoute): void
+    public function setTargetRoute(MarkedRoute $markedRoute, bool $allowDuplicate = false): void
     {
-        if ($this->targetRoute !== null) {
+        if ($this->targetRoute !== null && ! $allowDuplicate) {
             throw new DuplicateRouteException($markedRoute->route);
         }
 
-        $this->targetRoute = $markedRoute;
+        if ($this->targetRoute === null) {
+            $this->targetRoute = $markedRoute;
+        }
     }
 
     private static function convertDynamicSegmentToRegex(string $uriPart): string
     {
-        $regex = '#\{' . DiscoveredRoute::ROUTE_PARAM_NAME_REGEX . DiscoveredRoute::ROUTE_PARAM_CUSTOM_REGEX . '\}#';
+        $regex = '#\{' . DiscoveredRoute::ROUTE_PARAM_NAME_REGEX . DiscoveredRoute::ROUTE_PARAM_OPTIONAL_REGEX . DiscoveredRoute::ROUTE_PARAM_CUSTOM_REGEX . '\}#';
 
         return preg_replace_callback(
             $regex,
-            static fn ($matches) => trim($matches[2] ?? DiscoveredRoute::DEFAULT_MATCHING_GROUP),
+            static fn ($matches) => trim($matches[3] ?? DiscoveredRoute::DEFAULT_MATCHING_GROUP),
             $uriPart,
         );
     }

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

@@ -27,12 +27,33 @@ public function add(MarkedRoute $markedRoute): void
         // @mago-expect lint:no-multi-assignments
         $node = $this->roots[$method->value] ??= RouteTreeNode::createRootRoute();
 
+        $segments = $markedRoute->route->split();
+        $hasOptionalParams = false;
+
         // Traverse the tree and find the node for each route segment
-        foreach ($markedRoute->route->split() as $routeSegment) {
+        foreach ($segments as $index => $routeSegment) {
+            $isOptional = $this->isOptionalSegment($routeSegment);
+
+            if ($isOptional) {
+                $hasOptionalParams = true;
+                $node->setTargetRoute($markedRoute, allowDuplicate: true);
+                $routeSegment = $this->stripOptionalMarker($routeSegment);
+            }
+
             $node = $node->findOrCreateNodeForSegment($routeSegment);
         }
 
-        $node->setTargetRoute($markedRoute);
+        $node->setTargetRoute($markedRoute, allowDuplicate: $hasOptionalParams);
+    }
+
+    private function isOptionalSegment(string $segment): bool
+    {
+        return str_contains($segment, '?');
+    }
+
+    private function stripOptionalMarker(string $segment): string
+    {
+        return str_replace('?', '', $segment);
     }
 
     /** @return array<string, MatchingRegex> */

packages/router/src/Routing/Matching/GenericRouteMatcher.php

@@ -80,7 +80,24 @@ private function extractParams(DiscoveredRoute $route, array $routeMatches): arr
         $valueMap = [];
 
         foreach ($route->parameters as $i => $param) {
-            $value = $routeMatches[$i + 1];
+            $value = $routeMatches[$i + 1] ?? null;
+            $isOptional = $route->optionalParameters[$param] ?? false;
+
+            if ($value === null || $value === '') {
+                if (! $isOptional) {
+                    continue;
+                }
+
+                $parameterReflector = $route->handler->getParameter($param);
+
+                if ($parameterReflector && $parameterReflector->hasDefaultValue()) {
+                    $valueMap[$param] = $parameterReflector->getDefaultValue();
+
+                    continue;
+                }
+
+                continue;
+            }
 
             $parameterReflector = $route->handler->getParameter($param);