Allow for custom ConfigureRoutes implementations

[pmjones]

This PR adds a useCustomConfigureRoutes() method to FastRoute to allow for custom ConfigureRoutes implementations.

Also in FastRoute:

• rename $configuredRoutes and $routeConfiguration to $configureRoutes for consistency
• add configureRoutes() method to allow testing for the custom implementation
• rename buildConfiguration() to processedConfiguration(), and make public so utilities (such as a URL dumper) can examine the routes
• make RouteCollector non-final so it can be extended by consumers, e.g. to auto-add route names

(Note that I modified and force-pushed this PR after initial submission; my apologies for the hassle.)

[lcobucci]

Thanks, I was planning to work on this in the upcoming week 👍

Just please don't open the API more than strictly needed to have this change.

[lcobucci]

This is has been added on purpose and we'll make this class final on v3

[pmjones]

This is has been added on purpose

If I may ask, for what purpose was it added? Making it final means something like CastRouteCollector cannot capture or modify information along the way, without (essentially) copying the entire RouteCollector class to replace it.

[lcobucci]

The goal is to move the focus of people extending components away from the implementation details and give me flexibility on evolving the lib.

We can introduce ways to reduce boilerplate in the downstream if that's helpful, I just prefer to favour composition over inheritance for that component.

[pmjones]

After having tried my hand at it, composition-over-inheritance is difficult to implement with RouteCollector. After creating a decorator around it and modifying addRoute() to automatically add a route name, I realized that addGroup() calls $this internally, which means FastRoute\RouteCollector will use its own instance methods, and not the decorator instance methods. For example:

use FastRoute\RouteCollector as RouteCollector;
use FastRoute\ConfigureRoutes;

class DecoRouteCollector implements ConfigureRoutes
    public function __construct(
        protected RouteCollector $fastRouteCollector,
    ) {
    }

    /**
     * @inheritdoc
     */
    public function addRoute(string|array $httpMethod, string $route, mixed $handler, array $extraParameters = []): void
    {
        if (is_string($handler)) {
            $extraParameters[self::ROUTE_NAME] ??= $handler;
        }

        $this->fastRouteCollector->addRoute($httpMethod, $route, $handler, $extraParameters);
    }

    public function addGroup(string $prefix, callable $callback): void
    {
        // uses the FastRoute collector addRoute() under the hood,
        // not the decorator addRoute() method.
        $this->fastRouteCollector->addGroup($prefix, $callback);
    }
}

I think the easiest solution here still is to make RouteCollector non-final and allow extension.

[lcobucci]

This is not needed, as we just need to implement the interface.

[lcobucci]

This is meant to be encapsulated, please don't make it public

[pmjones]

This is meant to be encapsulated

/me nods along

Is there a suggestion for how to inspect the processed routes, so that someone might (for example) dump a list of what paths map to what handlers?

[lcobucci]

There are open issues about dumping that info and I was planning to introduce something that consolidates it in a standard structure for debugging.

[lcobucci]

Having an instance that implements should also be helpful

[pmjones]

That instance would be the FakeRouteCollector, referenced above.

[lcobucci]

Sorry, I was multi-tasking and communicated poorly.

I meant to say having the ability to receive an instance. Your point on #280 makes a lot of sense, so we could postpone changes and enhance the design using closures in a separate pr.

[pmjones]

we could postpone changes and enhance the design using closures in a separate pr

I have posted an alternative solution that incorporates something like "real" DI instead at #282 -- let me know if you think that path (or some variation of it) is viable.

[lcobucci]

Note that I modified and force-pushed this PR after initial submission; my apologies for the hassle.

Don't worry about that, force pushing is part of my flow and I really appreciate having a clear set of commits.