📝 Add docstrings to tree-node-storage

Docstrings generation was requested by @koriym.

* #208 (comment)

The following files were modified:

* `src/Map.php`
* `src/Matcher.php`
* `tests/Benchmark/GeneratorBench.php`
* `tests/Benchmark/MatchBench.php`

Author: coderabbitai[bot]

src/Map.php

@@ -387,23 +387,15 @@ public function put($name, $path, $handler = null)
         return $route;
     }
 
-    /**
-     *
-     * Attaches routes to a specific path prefix, and prefixes the attached
-     * route names.
-     *
-     * @param string $namePrefix The prefix for all route names being attached.
-     *
-     * @param string $pathPrefix The prefix for all route paths being attached.
-     *
-     * @param callable $callable A callable that uses the Map to add new
-     * routes. Its signature is `function (\Aura\Router\Map $map)`; $this
-     * Map instance will be passed to the callable.
+    /****
+     * Groups routes under a common name and path prefix, applying the prefixes to all routes added within the provided callable.
      *
-     * @throws Exception\ImmutableProperty
-     *
-     * @return void
+     * Temporarily updates the prototype route with the given name and path prefixes, invokes the callable to add routes using the updated prototype, and then restores the original prototype. All routes added within the callable will have the specified prefixes applied.
      *
+     * @param string $namePrefix Prefix to prepend to the names of attached routes.
+     * @param string $pathPrefix Prefix to prepend to the paths of attached routes.
+     * @param callable $callable Function that receives this map instance and adds routes.
+     * @throws Exception\ImmutableProperty If the prototype route's properties are immutable.
      */
     public function attach($namePrefix, $pathPrefix, callable $callable)
     {
@@ -420,4 +412,53 @@ public function attach($namePrefix, $pathPrefix, callable $callable)
         $callable($this);
         $this->protoRoute = $old;
     }
+
+    /****
+     * Converts all routable routes with defined paths into a hierarchical tree structure keyed by path segments.
+     *
+     * Each route path is normalized by replacing grouped optional parameters and individual parameters with generic placeholders (`{}`), then split into segments to build a nested associative array. Routes are stored at leaf nodes keyed by their object hash, and routes with grouped optional parameters are also stored at parent nodes. This structure optimizes route matching by reducing the number of routes to check per segment.
+     *
+     * @return array<string, Route|array<string, mixed>> Nested array representing the route tree, where each segment is a key and parameter segments use the key '{}'.
+     */
+    public function getAsTreeRouteNode()
+    {
+        $treeRoutes = [];
+        foreach ($this->routes as $route) {
+            if (! $route->isRoutable || $route->path === null) {
+                continue;
+            }
+
+            // replace "{/year,month,day}" parameters with /{}/{}/{}
+            $routePath = preg_replace_callback(
+                '~{/((?:\w+,?)+)}~',
+                static function (array $matches) {
+                    $variables = explode(',', $matches[1]);
+
+                    return '/' . implode('/', array_fill(0, count($variables), '{}'));
+                },
+                $route->path
+            ) ?: $route->path;
+            $paramsAreOptional = $routePath !== $route->path;
+
+            // This regexp will also work with "{controller:[a-zA-Z][a-zA-Z0-9_-]{1,}}"
+            $routePath = preg_replace('~{(?:[^{}]*|(?R))*}~', '{}', $routePath) ?: $routePath;
+            $node = &$treeRoutes;
+            foreach (explode('/', trim($routePath, '/')) as $segment) {
+                if (strpos($segment, '{') === 0) {
+                    if ($paramsAreOptional) {
+                        $node[spl_object_hash($route)] = $route;
+                    }
+                    $node = &$node['{}'];
+                    $node[spl_object_hash($route)] = $route;
+                    continue;
+                }
+                $node = &$node[$segment];
+            }
+
+            $node[spl_object_hash($route)] = $route;
+            unset($node);
+        }
+
+        return $treeRoutes;
+    }
 }

src/Matcher.php

@@ -96,15 +96,13 @@ public function __construct(
         $this->ruleIterator = $ruleIterator;
     }
 
-    /**
-     *
-     * Gets a route that matches the request.
+    /****
+     * Attempts to find and return the first route that matches the given HTTP request.
      *
-     * @param ServerRequestInterface $request The incoming request.
-     *
-     * @return Route|false Returns a route object when it finds a match, or
-     * boolean false if there is no match.
+     * Filters candidate routes based on the request path, then applies matching rules to each candidate until a match is found. Returns the matched route or false if no route matches.
      *
+     * @param ServerRequestInterface $request The HTTP request to match against available routes.
+     * @return Route|false The matched route object, or false if no route matches the request.
      */
     public function match(ServerRequestInterface $request)
     {
@@ -113,8 +111,12 @@ public function match(ServerRequestInterface $request)
         $this->failedScore = 0;
         $path = $request->getUri()->getPath();
 
-        foreach ($this->map as $name => $proto) {
-            $route = $this->requestRoute($request, $proto, $name, $path);
+        $possibleRoutes = $this->getMatchedTree($path);
+        foreach ($possibleRoutes as $proto) {
+            if (is_array($proto)) {
+                continue;
+            }
+            $route = $this->requestRoute($request, $proto, $path);
             if ($route) {
                 return $route;
             }
@@ -123,28 +125,23 @@ public function match(ServerRequestInterface $request)
         return false;
     }
 
-    /**
-     *
-     * Match a request to a route.
+    /****
+     * Attempts to match a proto-route to the given request and path.
      *
-     * @param ServerRequestInterface $request The request to match against.
-     *
-     * @param Route $proto The proto-route to match against.
-     *
-     * @param string $name The route name.
+     * Clones the provided proto-route and applies matching rules to determine if it matches the request and path.
      *
+     * @param ServerRequestInterface $request The HTTP request to match.
+     * @param Route $proto The proto-route candidate.
      * @param string $path The request path.
-     *
-     * @return mixed False on failure, or a Route on match.
-     *
+     * @return Route|false The matched Route on success, or false if the proto-route is not routable or does not match.
      */
-    protected function requestRoute($request, $proto, $name, $path)
+    protected function requestRoute($request, $proto, $path)
     {
         if (! $proto->isRoutable) {
-            return;
+            return false;
         }
         $route = clone $proto;
-        return $this->applyRules($request, $route, $name, $path);
+        return $this->applyRules($request, $route, $route->name, $path);
     }
 
     /**
@@ -247,18 +244,35 @@ public function getFailedRoute()
         return $this->failedRoute;
     }
 
-    /**
-     *
-     * Returns the result of the call to match() again so you don't need to
-     * run the matching process again.
-     *
-     * @return Route|false|null Returns null if match() has not been called
-     * yet, false if it has and there was no match, or a Route object if there
-     * was a match.
+    /****
+     * Retrieves the result of the most recent route matching attempt.
      *
+     * @return Route|false|null The matched Route object, false if no route matched, or null if matching has not been attempted.
      */
     public function getMatchedRoute()
     {
         return $this->matchedRoute;
     }
+
+    /****
+     * Traverses the route map tree according to the given URL path segments and returns an iterator over the matching subtree of routes.
+     *
+     * @param string $path The URL path to match, e.g., "/users/123".
+     * @return \RecursiveArrayIterator Iterator over the subtree of routes matching the path segments.
+     */
+    private function getMatchedTree($path)
+    {
+        $node = $this->map->getAsTreeRouteNode();
+        foreach (explode('/', trim($path, '/')) as $segment) {
+            if (isset($node[$segment])) {
+                $node = $node[$segment];
+                continue;
+            }
+            if (isset($node['{}'])) {
+                $node = $node['{}'];
+            }
+        }
+
+        return new \RecursiveArrayIterator($node);
+    }
 }

tests/Benchmark/GeneratorBench.php

@@ -0,0 +1,73 @@
+<?php
+
+namespace Aura\Router\Benchmark;
+
+use Aura\Router\Generator;
+use Aura\Router\Map;
+use Aura\Router\Route;
+
+/**
+ * @BeforeMethods("setUp")
+ */
+class GeneratorBench
+{
+    /**
+     * @var Generator
+     */
+    private $generator;
+
+    /**
+     * Prepares the route map and initializes the Generator instance for benchmarking.
+     *
+     * Populates the route map with dynamically generated routes and a complex 'dummy' route, then creates the Generator used in benchmark tests.
+     */
+    public function setUp()
+    {
+        $map = new Map(new Route());
+        foreach ($this->routesProvider() as $key => $route) {
+            $map->get($key, $route, static function () use ($key) { return $key; });
+        }
+
+        $map->get('dummy', '/api/user/{id}/{action}/{controller:[a-zA-Z][a-zA-Z0-9_-]{1,}}{/param1,param2}');
+        $this->generator = new Generator($map);
+    }
+
+
+    /**
+     * Yields a series of route paths with incremental segments and numeric suffixes.
+     *
+     * Each yielded key is a string in the format "{segmentIndex}-{routeNumber}", and the value is the corresponding route path composed of cumulative segments and a numeric suffix.
+     *
+     * @return \Generator<string, string> Generator yielding route keys and their corresponding paths.
+     */
+    private function routesProvider()
+    {
+        $segments = ['one', 'two', 'three', 'four', 'five', 'six'];
+        $routesPerSegment = 100;
+
+        $routeSegment = '';
+        foreach ($segments as $index => $segment) {
+            $routeSegment .= '/' . $segment;
+            for ($i = 1; $i <= $routesPerSegment; $i++) {
+                yield $index . '-' . $i => $routeSegment . $i;
+            }
+        }
+    }
+
+
+    /**
+     * Benchmarks the URL generation for the 'dummy' route with a fixed set of parameters.
+     *
+     * Executes 1000 repetitions per iteration over 10 iterations to measure the performance of the route generator.
+     */
+    public function benchMatch()
+    {
+        $this->generator->generate('dummy', [
+            'id' => 1,
+            'action' => 'doSomethingAction',
+            'controller' => 'My_User-Controller1',
+            'param1' => 'value1',
+            'param2' => 'value2',
+        ]);
+    }
+}

tests/Benchmark/MatchBench.php

@@ -0,0 +1,86 @@
+<?php
+
+namespace Aura\Router\Benchmark;
+
+use Aura\Router\RouterContainer;
+use GuzzleHttp\Psr7\ServerRequest;
+use Psr\Http\Message\ServerRequestInterface;
+
+/**
+ * @BeforeMethods("setUp")
+ */
+class MatchBench
+{
+    /** @var RouterContainer $container */
+    private $container;
+    /**
+     * @var \Aura\Router\Route[]|\mixed[][]
+     */
+    private $treeNodes;
+
+    /**
+     * Prepares the router container and populates it with a set of generated GET routes for benchmarking.
+     *
+     * Initializes the route map with routes from the provider and stores the resulting route tree structure for later use.
+     */
+    public function setUp()
+    {
+        $this->container = new RouterContainer();
+        $map = $this->container->getMap();
+
+        foreach ($this->routesProvider() as $key => $route) {
+            $map->get($key, $route, static function () use ($key) { return $key; });
+        }
+
+        $this->treeNodes = $map->getAsTreeRouteNode();
+    }
+
+    /**
+     * Benchmarks the performance of matching a set of generated routes against the router.
+     *
+     * Restores the pre-built route tree, then iterates through all generated routes, converting each to a request and verifying that it matches. Throws a RuntimeException if any route fails to match.
+     */
+    public function benchMatch()
+    {
+        $this->container->getMap()->treeRoutes = $this->treeNodes;
+        $matcher = $this->container->getMatcher();
+        foreach ($this->routesProvider() as $route) {
+            $result = $matcher->match($this->stringToRequest($route));
+            if ($result === false) {
+                throw new \RuntimeException(sprintf('Expected route "%s" to be an match', $route));
+            }
+        }
+    }
+
+    /**
+     * Generates a sequence of route strings by incrementally building path segments and appending numeric suffixes.
+     *
+     * Yields 600 routes in total, with each route keyed by its segment index and number (e.g., "2-45") and valued as the corresponding path (e.g., "/one/two/three45").
+     *
+     * @return \Generator<string, string> Route keys mapped to their corresponding path strings.
+     */
+    private function routesProvider()
+    {
+        $segments = ['one', 'two', 'three', 'four', 'five', 'six'];
+        $routesPerSegment = 100;
+
+        $routeSegment = '';
+        foreach ($segments as $index => $segment) {
+            $routeSegment .= '/' . $segment;
+            for ($i = 1; $i <= $routesPerSegment; $i++) {
+                yield $index . '-' . $i => $routeSegment . $i;
+            }
+        }
+    }
+
+    /****
+     * Creates a PSR-7 ServerRequest object for a GET request to the specified URL.
+     *
+     * @param string $url The URL to use for the request.
+     * @return ServerRequestInterface A ServerRequest instance representing a GET request to the given URL.
+     */
+    private function stringToRequest($url)
+    {
+        return new ServerRequest('GET', $url, [], null, '1.1', []);
+    }
+}