feat(router): improve optional route parameter syntax (#1706)

Author: xHeaven

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

@@ -12,6 +12,8 @@ final class DiscoveredRoute implements Route
 {
     public const string DEFAULT_MATCHING_GROUP = '[^/]++';
 
+    public const string ROUTE_PARAM_OPTIONAL_REGEX = '(\??)';
+
     public const string ROUTE_PARAM_NAME_REGEX = '(\w*)';
 
     public const string ROUTE_PARAM_CUSTOM_REGEX = '(?::([^{}]*(?:\{(?-1)\}[^{}]*)*))?';
@@ -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_OPTIONAL_REGEX . self::ROUTE_PARAM_NAME_REGEX . self::ROUTE_PARAM_CUSTOM_REGEX . '\}#';
 
         preg_match_all($regex, $uriPart, $matches);
 
-        return $matches[1] ?? [];
+        $optionalMarkers = $matches[1] ?? [];
+        $names = $matches[2] ?? [];
+
+        $optional = [];
+        foreach ($names as $i => $name) {
+            $optional[$name] = $optionalMarkers[$i] === '?';
+        }
+
+        return [
+            'names' => $names,
+            'optional' => $optional,
+        ];
     }
 
     /**

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

@@ -61,11 +61,11 @@ public function setTargetRoute(MarkedRoute $markedRoute): void
 
     private static function convertDynamicSegmentToRegex(string $uriPart): string
     {
-        $regex = '#\{' . DiscoveredRoute::ROUTE_PARAM_NAME_REGEX . DiscoveredRoute::ROUTE_PARAM_CUSTOM_REGEX . '\}#';
+        $regex = '#\{' . DiscoveredRoute::ROUTE_PARAM_OPTIONAL_REGEX . DiscoveredRoute::ROUTE_PARAM_NAME_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,14 +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();
+
         // Traverse the tree and find the node for each route segment
-        foreach ($markedRoute->route->split() as $routeSegment) {
+        foreach ($segments as $routeSegment) {
+            $isOptional = $this->isOptionalSegment($routeSegment);
+
+            if ($isOptional) {
+                $node->setTargetRoute($markedRoute);
+                $routeSegment = $this->stripOptionalMarker($routeSegment);
+            }
+
             $node = $node->findOrCreateNodeForSegment($routeSegment);
         }
 
         $node->setTargetRoute($markedRoute);
     }
 
+    private function isOptionalSegment(string $segment): bool
+    {
+        return str_starts_with($segment, '{?');
+    }
+
+    private function stripOptionalMarker(string $segment): string
+    {
+        return str_replace('?', '', $segment);
+    }
+
     /** @return array<string, MatchingRegex> */
     public function toMatchingRegexes(): array
     {

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

@@ -80,11 +80,28 @@ 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?->hasDefaultValue()) {
+                    $valueMap[$param] = $parameterReflector->getDefaultValue();
+
+                    continue;
+                }
+
+                continue;
+            }
 
             $parameterReflector = $route->handler->getParameter($param);
 
-            if ($parameterReflector && $parameterReflector->getType()?->isBackedEnum()) {
+            if ($parameterReflector?->getType()->isBackedEnum()) {
                 $value = $parameterReflector->getType()->asClass()->callStatic('tryFrom', $value);
 
                 if ($value === null) {

packages/router/tests/FakeRouteBuilderWithOptionalParams.php

@@ -0,0 +1,70 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Router\Tests;
+
+use ReflectionMethod;
+use Tempest\Http\Method;
+use Tempest\Reflection\MethodReflector;
+use Tempest\Router\HttpMiddleware;
+use Tempest\Router\Route;
+use Tempest\Router\Routing\Construction\DiscoveredRoute;
+use Tempest\Router\Routing\Construction\MarkedRoute;
+
+final class FakeRouteBuilderWithOptionalParams implements Route
+{
+    private MethodReflector $handler;
+
+    public function __construct(
+        public Method $method = Method::GET,
+        public string $uri = '/',
+        /** @var class-string<HttpMiddleware>[] */
+        public array $middleware = [],
+        public array $without = [],
+        private string $handlerMethod = 'handler',
+    ) {
+        $this->handler = new MethodReflector(new ReflectionMethod($this, $this->handlerMethod));
+    }
+
+    public function withUri(string $uri): self
+    {
+        return new self($this->method, $uri, $this->middleware, $this->without, $this->handlerMethod);
+    }
+
+    public function withMethod(Method $method): self
+    {
+        return new self($method, $this->uri, $this->middleware, $this->without, $this->handlerMethod);
+    }
+
+    public function withHandler(string $handlerMethod): self
+    {
+        return new self($this->method, $this->uri, $this->middleware, $this->without, $handlerMethod);
+    }
+
+    public function asMarkedRoute(string $mark): MarkedRoute
+    {
+        return new MarkedRoute($mark, $this->asDiscoveredRoute());
+    }
+
+    public function asDiscoveredRoute(): DiscoveredRoute
+    {
+        return DiscoveredRoute::fromRoute($this, [], $this->handler);
+    }
+
+    public function handler(): void
+    {
+    }
+
+    public function handlerWithOptionalId(string $id = 'default-id'): void
+    {
+    }
+
+    public function handlerWithTwoOptionalParams(string $id = 'default-id', string $slug = 'default-slug'): void
+    {
+    }
+
+    public function handlerWithRequiredAndOptional(string $id, string $slug = 'default-slug'): void
+    {
+    }
+}