Route collector

[jamesrweb]

As I have discussed in #216 here with @SimonFrings, a native route collector would be really helpful. For my own purposes I built one which you may or may not base the "native" version on.

Note:

Since I use PHPStan throughout my projects, there are some phpstan specific PHPDocs here for reference purposes.

Implementation

/**
 * @phpstan-type Path string
 * @phpstan-type VerbMap array<HttpVerb, RouteHandler>
 * @phpstan-type GroupMap array<Path, RouteCollector>
 * @phpstan-type RouteMap array<Path, VerbMap>
 * @phpstan-type RouteHandler (callable(ServerRequestInterface): ResponseInterface)|class-string
 * @phpstan-type HttpVerb 'GET'|'POST'|'PUT'|'PATCH'|'DELETE'|'OPTIONS'|'HEAD'|'ANY'
 */
class RouteCollector
{
    /**
     * @phpstan-var RouteMap
     *
     * @var array<string, array<string, callable|string>>
     */
    private array $routes = [];

    /**
     * @phpstan-var GroupMap
     *
     * @var array<string, RouteCollector>
     */
    private array $groups = [];

    public function __construct(private readonly App $app, private readonly string $basePath)
    {
    }

    /**
     * @param callable(RouteCollector): void $callback
     */
    public function addGroup(string $path, callable $callback): void
    {
        $path = $this->normalisePath($path);
        $next = new self($this->app, $path);
        $this->groups[$path] = $next;

        $callback($next);
    }

    /**
     * @phpstan-param RouteHandler $callback
     */
    public function get(string $path, callable|string $callback): void
    {
        $path = $this->normalisePath($path);

        if (!array_key_exists($path, $this->routes)) {
            $this->routes[$path] = [];
        }

        $this->routes[$path]['GET'] = $callback;

        $this->app->get($path, $callback);
    }

    /**
     * @phpstan-param RouteHandler $callback
     */
    public function post(string $path, callable|string $callback): void
    {
        $path = $this->normalisePath($path);

        if (!array_key_exists($path, $this->routes)) {
            $this->routes[$path] = [];
        }

        $this->routes[$path]['POST'] = $callback;

        $this->app->post($path, $callback);
    }

    /**
     * @phpstan-param RouteHandler $callback
     */
    public function put(string $path, callable|string $callback): void
    {
        $path = $this->normalisePath($path);

        if (!array_key_exists($path, $this->routes)) {
            $this->routes[$path] = [];
        }

        $this->routes[$path]['PUT'] = $callback;

        $this->app->put($path, $callback);
    }

    /**
     * @phpstan-param RouteHandler $callback
     */
    public function patch(string $path, callable|string $callback): void
    {
        $path = $this->normalisePath($path);

        if (!array_key_exists($path, $this->routes)) {
            $this->routes[$path] = [];
        }

        $this->routes[$path]['PATCH'] = $callback;

        $this->app->patch($path, $callback);
    }

    /**
     * @phpstan-param RouteHandler $callback
     */
    public function delete(string $path, callable|string $callback): void
    {
        $path = $this->normalisePath($path);

        if (!array_key_exists($path, $this->routes)) {
            $this->routes[$path] = [];
        }

        $this->routes[$path]['DELETE'] = $callback;

        $this->app->delete($path, $callback);
    }

    /**
     * @phpstan-param RouteHandler $callback
     */
    public function options(string $path, callable|string $callback): void
    {
        $path = $this->normalisePath($path);

        if (!array_key_exists($path, $this->routes)) {
            $this->routes[$path] = [];
        }

        $this->routes[$path]['OPTIONS'] = $callback;

        $this->app->options($path, $callback);
    }

    /**
     * @phpstan-param RouteHandler $callback
     */
    public function head(string $path, callable|string $callback): void
    {
        $path = $this->normalisePath($path);

        if (!array_key_exists($path, $this->routes)) {
            $this->routes[$path] = [];
        }

        $this->routes[$path]['HEAD'] = $callback;

        $this->app->head($path, $callback);
    }

    /**
     * @phpstan-param RouteHandler $callback
     */
    public function any(string $path, callable|string $callback): void
    {
        $path = $this->normalisePath($path);

        $this->get($path, $callback);
        $this->post($path, $callback);
        $this->put($path, $callback);
        $this->patch($path, $callback);
        $this->delete($path, $callback);
        $this->options($path, $callback);
        $this->head($path, $callback);
    }

    /**
     * @phpstan-return RouteMap
     *
     * @return array<string, array<HttpVerb, RouteHandler>>
     */
    public function getRoutes(): array
    {
        $routes = array_merge([], $this->routes);
        $groups = array_merge([], $this->groups);

        while (count($groups) > 0) {
            $group = array_shift($groups);
            $routes = array_merge($routes, $group->getRoutes());
            $groups = array_merge($groups, $group->getGroups());
        }

        return array_merge($this->routes, $routes);
    }

    /**
     * @phpstan-return GroupMap
     *
     * @return array<string, RouteCollector>
     */
    public function getGroups(): array
    {
        return $this->groups;
    }

    public function getBasePath(): string
    {
        return $this->basePath;
    }

    private function normalisePath(string $path): string
    {
        if (str_starts_with($path, $this->basePath)) {
            $path = substr($path, strlen($this->basePath));
        }

        if (!str_starts_with($path, '/')) {
            $path = '/'.$path;
        }

        if (str_ends_with($path, '/')) {
            $path = substr($path, 0, -1);
        }

        return $this->basePath.$path;
    }
}

Tests

#[CoversClass(RouteCollector::class)]
class RouteCollectorTest extends TestCase
{
    private string $basePath;
    private RouteCollector $routeCollector;

    public function setUp(): void
    {
        $app = new App();
        $this->basePath = '/api';
        $this->routeCollector = new RouteCollector($app, $this->basePath);
    }

    public function testGet(): void
    {
        $handler = fn (): ResponseInterface => new Response();
        $this->routeCollector->get('/test', $handler);

        $routes = $this->routeCollector->getRoutes();

        RouteCollectorTest::assertArrayHasKey('/api/test', $routes);
        RouteCollectorTest::assertArrayHasKey('GET', $routes['/api/test']);
        RouteCollectorTest::assertEquals($handler, $routes['/api/test']['GET']);
    }

    public function testPost(): void
    {
        $handler = fn (): ResponseInterface => new Response();
        $this->routeCollector->post('/test', $handler);

        $routes = $this->routeCollector->getRoutes();

        RouteCollectorTest::assertArrayHasKey('/api/test', $routes);
        RouteCollectorTest::assertArrayHasKey('POST', $routes['/api/test']);
        RouteCollectorTest::assertEquals($handler, $routes['/api/test']['POST']);
    }

    public function testPut(): void
    {
        $handler = fn (): ResponseInterface => new Response();
        $this->routeCollector->put('/test', $handler);

        $routes = $this->routeCollector->getRoutes();

        RouteCollectorTest::assertArrayHasKey('/api/test', $routes);
        RouteCollectorTest::assertArrayHasKey('PUT', $routes['/api/test']);
        RouteCollectorTest::assertEquals($handler, $routes['/api/test']['PUT']);
    }

    public function testPatch(): void
    {
        $handler = fn (): ResponseInterface => new Response();
        $this->routeCollector->patch('/test', $handler);

        $routes = $this->routeCollector->getRoutes();

        RouteCollectorTest::assertArrayHasKey('/api/test', $routes);
        RouteCollectorTest::assertArrayHasKey('PATCH', $routes['/api/test']);
        RouteCollectorTest::assertEquals($handler, $routes['/api/test']['PATCH']);
    }

    public function testDelete(): void
    {
        $handler = fn (): ResponseInterface => new Response();
        $this->routeCollector->delete('/test', $handler);

        $routes = $this->routeCollector->getRoutes();

        RouteCollectorTest::assertArrayHasKey('/api/test', $routes);
        RouteCollectorTest::assertArrayHasKey('DELETE', $routes['/api/test']);
        RouteCollectorTest::assertEquals($handler, $routes['/api/test']['DELETE']);
    }

    public function testOptions(): void
    {
        $handler = fn (): ResponseInterface => new Response();
        $this->routeCollector->options('/test', $handler);

        $routes = $this->routeCollector->getRoutes();

        RouteCollectorTest::assertArrayHasKey('/api/test', $routes);
        RouteCollectorTest::assertArrayHasKey('OPTIONS', $routes['/api/test']);
        RouteCollectorTest::assertEquals($handler, $routes['/api/test']['OPTIONS']);
    }

    public function testHead(): void
    {
        $handler = fn (): ResponseInterface => new Response();
        $this->routeCollector->head('/test', $handler);

        $routes = $this->routeCollector->getRoutes();

        RouteCollectorTest::assertArrayHasKey('/api/test', $routes);
        RouteCollectorTest::assertArrayHasKey('HEAD', $routes['/api/test']);
        RouteCollectorTest::assertEquals($handler, $routes['/api/test']['HEAD']);
    }

    public function testAny(): void
    {
        $handler = fn (): ResponseInterface => new Response();
        $this->routeCollector->any('/test', $handler);

        $routes = $this->routeCollector->getRoutes();

        RouteCollectorTest::assertArrayHasKey('/api/test', $routes);
        RouteCollectorTest::assertArrayHasKey('GET', $routes['/api/test']);
        RouteCollectorTest::assertEquals($handler, $routes['/api/test']['GET']);
        RouteCollectorTest::assertArrayHasKey('POST', $routes['/api/test']);
        RouteCollectorTest::assertEquals($handler, $routes['/api/test']['POST']);
        RouteCollectorTest::assertArrayHasKey('PUT', $routes['/api/test']);
        RouteCollectorTest::assertEquals($handler, $routes['/api/test']['PUT']);
        RouteCollectorTest::assertArrayHasKey('PATCH', $routes['/api/test']);
        RouteCollectorTest::assertEquals($handler, $routes['/api/test']['PATCH']);
        RouteCollectorTest::assertArrayHasKey('DELETE', $routes['/api/test']);
        RouteCollectorTest::assertEquals($handler, $routes['/api/test']['DELETE']);
        RouteCollectorTest::assertArrayHasKey('OPTIONS', $routes['/api/test']);
        RouteCollectorTest::assertEquals($handler, $routes['/api/test']['OPTIONS']);
        RouteCollectorTest::assertArrayHasKey('HEAD', $routes['/api/test']);
        RouteCollectorTest::assertEquals($handler, $routes['/api/test']['HEAD']);
    }

    public function testGetRoutesInitialisesEmptyByDefault(): void
    {
        RouteCollectorTest::assertEquals([], $this->routeCollector->getRoutes());
    }

    public function testGetRoutesReturnsRoutes(): void
    {
        $handler = fn (): ResponseInterface => new Response();
        $this->routeCollector->get('/test', $handler);
        $this->routeCollector->put('/test2', $handler);
        $this->routeCollector->addGroup('/test3', function (RouteCollector $routeCollector) use ($handler): void {
            $routeCollector->get('/test4', $handler);
            $routeCollector->addGroup('/test5', function (RouteCollector $routeCollector) use ($handler): void {
                $routeCollector->get('/test6', $handler);
            });
        });

        $routes = $this->routeCollector->getRoutes();

        RouteCollectorTest::assertArrayHasKey('/api/test', $routes);
        RouteCollectorTest::assertArrayHasKey('GET', $routes['/api/test']);
        RouteCollectorTest::assertEquals($handler, $routes['/api/test']['GET']);
        RouteCollectorTest::assertArrayHasKey('/api/test2', $routes);
        RouteCollectorTest::assertArrayHasKey('PUT', $routes['/api/test2']);
        RouteCollectorTest::assertEquals($handler, $routes['/api/test2']['PUT']);
        RouteCollectorTest::assertArrayHasKey('/api/test3/test4', $routes);
        RouteCollectorTest::assertArrayHasKey('GET', $routes['/api/test3/test4']);
        RouteCollectorTest::assertEquals($handler, $routes['/api/test3/test4']['GET']);
        RouteCollectorTest::assertArrayHasKey('/api/test3/test5/test6', $routes);
        RouteCollectorTest::assertArrayHasKey('GET', $routes['/api/test3/test5/test6']);
        RouteCollectorTest::assertEquals($handler, $routes['/api/test3/test5/test6']['GET']);
    }

    public function testGetGroupsInitialisesEmptyByDefault(): void
    {
        RouteCollectorTest::assertEquals([], $this->routeCollector->getGroups());
    }

    public function testGetGroupsReturnsGroups(): void
    {
        $handler = fn (): ResponseInterface => new Response();
        $this->routeCollector->addGroup('/test', function (RouteCollector $routeCollector) use ($handler): void {
            $routeCollector->get('/test2', $handler);
        });
        $this->routeCollector->addGroup('/test3', function (RouteCollector $routeCollector) use ($handler): void {
            $routeCollector->get('/test4', $handler);
        });

        $groups = $this->routeCollector->getGroups();

        RouteCollectorTest::assertArrayHasKey('/api/test', $groups);
        RouteCollectorTest::assertArrayHasKey('/api/test3', $groups);
        RouteCollectorTest::assertInstanceOf(RouteCollector::class, $groups['/api/test']);
        RouteCollectorTest::assertInstanceOf(RouteCollector::class, $groups['/api/test3']);
    }

    public function testGetBasePath(): void
    {
        RouteCollectorTest::assertEquals($this->basePath, $this->routeCollector->getBasePath());
    }

    public function testPathsWithTrailingSlashesAreNormalized(): void
    {
        $handler = fn (): ResponseInterface => new Response();
        $this->routeCollector->get('/test/', $handler);
        $this->routeCollector->post('/test2', $handler);

        $routes = $this->routeCollector->getRoutes();

        RouteCollectorTest::assertArrayHasKey('/api/test', $routes);
        RouteCollectorTest::assertArrayHasKey('GET', $routes['/api/test']);
        RouteCollectorTest::assertEquals($handler, $routes['/api/test']['GET']);
        RouteCollectorTest::assertArrayHasKey('/api/test2', $routes);
        RouteCollectorTest::assertArrayHasKey('POST', $routes['/api/test2']);
        RouteCollectorTest::assertEquals($handler, $routes['/api/test2']['POST']);
    }

    public function testPathsWithoutPrefixSlashesAreNormalised(): void
    {
        $handler = fn (): ResponseInterface => new Response();
        $this->routeCollector->get('test/', $handler);
        $this->routeCollector->post('test2', $handler);

        $routes = $this->routeCollector->getRoutes();

        RouteCollectorTest::assertArrayHasKey('/api/test', $routes);
        RouteCollectorTest::assertArrayHasKey('GET', $routes['/api/test']);
        RouteCollectorTest::assertEquals($handler, $routes['/api/test']['GET']);
        RouteCollectorTest::assertArrayHasKey('/api/test2', $routes);
        RouteCollectorTest::assertArrayHasKey('POST', $routes['/api/test2']);
        RouteCollectorTest::assertEquals($handler, $routes['/api/test2']['POST']);
    }
}

Usage

$container = new Container(...);
$app = new App(...);
$apiV1RouteCollector = new RouteCollector($app, '/api/v1');

// Supported option #1
$apiV1RouteCollector->addGroup('/user', function (RouteCollector $userCollector) {
    $userCollector->get('', ReadUsersController::class);
    $userCollector->post('', CreateUserController::class);
    $userCollector->get('/{id}', ReadUserController::class);
    $userCollector->put('/{id}', UpdateUserController::class);
    $userCollector->delete('/{id}', DeleteUserController::class);
});

// Supported option #2
$apiV1RouteCollector->addGroup('/post', function (RouteCollector $postsCollector) {
    $postsCollector->get('', ReadPostsController::class);
    $postsCollector->post('', CreatePostController::class);
    
    postCollector->addGroup('/{id}', function (RouteCollector $postCollector) {
      $postCollector->get('', ReadPostController::class);
      $postCollector->put('', UpdatePostController::class);
      $postCollector->delete('', DeletePostController::class);
    }
});

While you can nest as much as you like but I haven't found a case for more than 3 levels deep.

I would improve this by adding trace and connect verb handlers but currently FrameworkX doesn't support these.. I believe it should be native to the project to support all restful verbs, etc but I am curious why they aren't there either way?

Otherwise this is a foundation I have been using in production with Framework-X now for a while and works quite well so far for my use cases.

[mimmi20]

Is there a reason, you do not support the MiddlewareInterface as Routehandler?

[jamesrweb]

Just not had the use case for it in my codebases. All middlewares I run execute before any route gets hit as part of the global middleware chain and so I never saw the need to add it to the route collector signature.

You could always adapt it to your needs. My main point with sharing this was to continue the conversation with @SimonFrings and gather feedback much like yours for @clue for example to consider. 😊

[SimonFrings]

@jamesrweb You definitely put some work into this, great job 👍

Are you suggesting to add this as part of Framework X or is this something that can/should exist outside of the project? In my opinion both ways work and have their pros and cons, for example adding this to the project itself also means to add additional documentation, ensure 100% code coverage, etc.

I'm interested in your thoughts on this.

[gabrielberthier]

I was writing a suggestion and trying to create some examples, but luckly I stumbled on your discussion. One thing I am considering before moving one of my PHP projects to use X instead of Slim is something like that, and I think it would be great to group routes based on a certain prefix.

[SimonFrings]

@jamesrweb, @gabrielberthier To keep you in the loop, I just updated #216 telling about our current progress. In short, with Framework X v0.16.0 now released we can start looking into the next big topics. We'll probably have to rework the handler structure as a first step (including the RouteHandler) and then take a look at route groups afterwards.

See also #241 for more details 👍

[gabrielberthier]

Great! Just for sheer curiosity, why the need to rework on the handler structure?

[SimonFrings]

@gabrielberthier This is more about design choices that were made in the past, but our perspective on them has evolved since then. We expect even more handlers to be part of Framework X in the near future, so we want to refactor all existing handlers by moving them into a separate namespace. Some of the currently implemented handlers will also receive additional refactorings like renames, API changes, etc., which most likely will involve some BC breaks.

We're not forced to wait on these refactorings in order to support route groups, but because we're expecting all the stated changes above, we can avoid foreseeable BC breaks regarding a route group implementation in the future. This also avoids doing double the work.

[gabrielberthier]

Thanks, Simon. Glad that you replied :)