Allow for custom ConfigureRoutes implementations

Also in FastRoute:

- rename $configuredRoutes and $routeConfiguration to $configureRoutes for consistency
- add processedRoutes() method to expose processed routes for examination, e.g. by a URL dumper
- add configureRoutes() method to allow testing for the custom implementation
- make RouteCollector non-final so it can be extended by consumers, e.g. to auto-add route names

src/FastRoute.php

@@ -20,7 +20,7 @@ final class FastRoute
      * @param class-string<RouteParser>      $routeParser
      * @param class-string<DataGenerator>    $dataGenerator
      * @param class-string<Dispatcher>       $dispatcher
-     * @param class-string<ConfigureRoutes>  $routesConfiguration
+     * @param class-string<ConfigureRoutes>  $configureRoutes
      * @param class-string<GenerateUri>      $uriGenerator
      * @param Cache|class-string<Cache>|null $cacheDriver
      * @param non-empty-string|null          $cacheKey
@@ -30,7 +30,7 @@ private function __construct(
         private readonly string $routeParser,
         private readonly string $dataGenerator,
         private readonly string $dispatcher,
-        private readonly string $routesConfiguration,
+        private readonly string $configureRoutes,
         private readonly string $uriGenerator,
         private readonly Cache|string|null $cacheDriver,
         private readonly ?string $cacheKey,
@@ -62,7 +62,7 @@ public function disableCache(): self
             $this->routeParser,
             $this->dataGenerator,
             $this->dispatcher,
-            $this->routesConfiguration,
+            $this->configureRoutes,
             $this->uriGenerator,
             null,
             null,
@@ -80,7 +80,7 @@ public function withCache(Cache|string $driver, string $cacheKey): self
             $this->routeParser,
             $this->dataGenerator,
             $this->dispatcher,
-            $this->routesConfiguration,
+            $this->configureRoutes,
             $this->uriGenerator,
             $driver,
             $cacheKey,
@@ -118,7 +118,24 @@ public function useCustomDispatcher(string $dataGenerator, string $dispatcher):
             $this->routeParser,
             $dataGenerator,
             $dispatcher,
-            $this->routesConfiguration,
+            $this->configureRoutes,
+            $this->uriGenerator,
+            $this->cacheDriver,
+            $this->cacheKey,
+        );
+    }
+
+    /**
+     * @param class-string<ConfigureRoutes> $configureRoutes
+     */
+    public function useCustomConfigureRoutes(string $configureRoutes): self
+    {
+        return new self(
+            $this->routeDefinitionCallback,
+            $this->routeParser,
+            $this->dataGenerator,
+            $this->dispatcher,
+            $configureRoutes,
             $this->uriGenerator,
             $this->cacheDriver,
             $this->cacheKey,
@@ -133,7 +150,7 @@ public function withUriGenerator(string $uriGenerator): self
             $this->routeParser,
             $this->dataGenerator,
             $this->dispatcher,
-            $this->routesConfiguration,
+            $this->configureRoutes,
             $uriGenerator,
             $this->cacheDriver,
             $this->cacheKey,
@@ -147,16 +164,7 @@ private function buildConfiguration(): array
             return $this->processedConfiguration;
         }
 
-        $loader = function (): array {
-            $configuredRoutes = new $this->routesConfiguration(
-                new $this->routeParser(),
-                new $this->dataGenerator(),
-            );
-
-            ($this->routeDefinitionCallback)($configuredRoutes);
-
-            return $configuredRoutes->processedRoutes();
-        };
+        $loader = $this->processedRoutes(...);
 
         if ($this->cacheDriver === null) {
             return $this->processedConfiguration = $loader();
@@ -171,6 +179,24 @@ private function buildConfiguration(): array
         return $this->processedConfiguration = $cache->get($this->cacheKey, $loader);
     }
 
+    /**
+     * @return ProcessedData
+     */
+    public function processedRoutes(): array
+    {
+        $configureRoutes = $this->configureRoutes();
+        ($this->routeDefinitionCallback)($configureRoutes);
+        return $configureRoutes->processedRoutes();
+    }
+
+    public function configureRoutes(): ConfigureRoutes
+    {
+        return new $this->configureRoutes(
+            new $this->routeParser(),
+            new $this->dataGenerator(),
+        );
+    }
+
     public function dispatcher(): Dispatcher
     {
         return new $this->dispatcher($this->buildConfiguration());

src/RouteCollector.php

@@ -12,7 +12,6 @@
  * @phpstan-import-type ExtraParameters from DataGenerator
  * @phpstan-import-type RoutesForUriGeneration from GenerateUri
  * @phpstan-import-type ParsedRoutes from RouteParser
- * @final
  */
 class RouteCollector implements ConfigureRoutes
 {

test/FakeRouteCollector.php

@@ -0,0 +1,10 @@
+<?php
+declare(strict_types=1);
+
+namespace FastRoute\Test;
+
+use FastRoute\RouteCollector;
+
+class FakeRouteCollector extends RouteCollector
+{
+}

test/FastRouteTest.php

@@ -8,6 +8,7 @@
 use FastRoute\Dispatcher;
 use FastRoute\FastRoute;
 use FastRoute\GenerateUri;
+use FastRoute\RouteCollector;
 use PHPUnit\Framework\Attributes as PHPUnit;
 use PHPUnit\Framework\TestCase;
 use RuntimeException;
@@ -110,6 +111,16 @@ public function defaultUriGeneratorMustBeProvided(): void
         self::assertInstanceOf(GenerateUri\FromProcessedConfiguration::class, $uriGenerator);
     }
 
+    #[PHPUnit\Test]
+    public function configureRoutesCanBeOverridden(): void
+    {
+        $configureRoutes = FastRoute::recommendedSettings(self::routes(...), 'test')
+            ->useCustomConfigureRoutes(FakeRouteCollector::class)
+            ->configureRoutes();
+
+        self::assertInstanceOf(FakeRouteCollector::class, $configureRoutes);
+    }
+
     #[PHPUnit\Test]
     public function uriGeneratorCanBeOverridden(): void
     {