v5 - Refactor routing to use RouteMatch and dispatcher interfaces by odan · Pull Request #3438 · slimphp/Slim

odan · 2026-04-03T14:31:37Z

This is a routing architecture refactor that replaces request attributes based on RouteContext::ROUTING_RESULTS with RouteMatch::class

Changes

Introduce DispatcherInterface and add FastRouteDispatcher as the default dispatcher implementation
Register DispatcherInterface in container definitions and resolve it via FastRouteDispatcher
Introduce RouteInterface and update Route to implement it
Add RouteMatch as the new immutable routing result object for found, not found, and method-not-allowed states
Refactor RoutingMiddleware to use injected dispatcher and attach RouteMatch to the request
Refactor EndpointMiddleware to consume RouteMatch instead of RoutingResults
Update RoutingArgumentsMiddleware to read route arguments from RouteMatch
Remove legacy RoutingResults and RouteContext classes
Move endpoint execution to interface-based route handling with improved validation and error messages
Refactor route middleware collection to preserve parent group to route-specific execution order
Add route argument storage and accessors to Route via getArgument(), getArguments(), and setArguments()
Add license headers and small cleanup improvements in routing-related classes
Update tests to validate RouteMatch behavior and replace legacy routing context/result assertions
Remove outdated tests for RouteContext and RoutingResults
Update changelog by removing the deprecation/removal note for setArguments and setArgument
Adjust base path handling to rely on router state instead of request route context attributes

coveralls · 2026-04-03T14:33:18Z

coverage: 96.162% (-0.8%) from 96.939%
when pulling 24993e5 on odan:5.x-route-arguments
into ad393ae on slimphp:5.x.

Copilot

Pull request overview

Refactors Slim v5 routing to replace request-attribute based RouteContext::ROUTING_RESULTS / RoutingResults with an immutable RouteMatch object and interface-driven dispatching, updating middleware and tests accordingly.

Changes:

Introduces DispatcherInterface with a default FastRouteDispatcher, and wires it into container definitions.
Adds RouteInterface and updates Route + routing/endpoint middleware to operate on RouteMatch attached to the request.
Replaces legacy routing context/results tests with RouteMatch-focused tests and removes deprecated classes/tests.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
tests/Routing/RoutingResultsTest.php	Removes legacy `RoutingResults` test coverage.
tests/Routing/RouteMatchTest.php	Adds tests for the new `RouteMatch` immutable routing result.
tests/Routing/RouteContextTest.php	Removes legacy `RouteContext` test coverage.
tests/Middleware/RoutingMiddlewareTest.php	Updates middleware tests to assert `RouteMatch` request attribute behavior.
tests/Middleware/BasePathMiddlewareTest.php	Updates base path assertions to use app/router state rather than request attributes.
Slim/Routing/RoutingResults.php	Removes legacy routing result object.
Slim/Routing/RouteMatch.php	Adds the new immutable routing result object.
Slim/Routing/RouteContext.php	Removes legacy routing context helper.
Slim/Routing/Route.php	Implements `RouteInterface` and adds route argument storage accessors.
Slim/Routing/FastRouteDispatcher.php	Adds default dispatcher implementation backed by FastRoute.
Slim/Middleware/RoutingMiddleware.php	Refactors routing middleware to use injected dispatcher and attach `RouteMatch`.
Slim/Middleware/RoutingArgumentsMiddleware.php	Reads route arguments from `RouteMatch` and attaches them to request attributes.
Slim/Middleware/EndpointMiddleware.php	Executes endpoints based on `RouteMatch` and refactors middleware collection ordering.
Slim/Middleware/BasePathMiddleware.php	Shifts base path handling to router state (removing request attribute use).
Slim/Interfaces/RouteInterface.php	Introduces a route abstraction consumed by routing components.
Slim/Interfaces/DispatcherInterface.php	Introduces a dispatcher abstraction for route matching.
Slim/Container/Definition/SlimDefinitions.php	Registers `DispatcherInterface` in the container using `FastRouteDispatcher`.
CHANGELOG.md	Updates changelog entries related to removed/deprecated routing APIs.

Comments suppressed due to low confidence (1)

Slim/Middleware/RoutingMiddleware.php:127

stripBasePath() blindly strips strlen($basePath) bytes from $uri without verifying that $uri actually starts with $basePath (or that $basePath is shorter than $uri). With a misconfigured base path this can turn unrelated paths into '/' and route incorrectly. Guard with a prefix check (and only strip when it matches), otherwise return the original $uri.

    private function stripBasePath(string $uri, string $basePath): string
    {
        // No base path configured
        if ($basePath === '' || $basePath === '/') {
            return $uri;
        }

        return '/' . ltrim(rtrim(substr($uri, strlen($basePath)), '/'), '/');
    }

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-03T14:35:45Z

Slim/Routing/Route.php

+     *
+     * @var array<string, string>
+     */
+    private array $arguments;


$arguments is a typed property but never initialized (no default value and not set in the constructor). Calling getArgument()/getArguments() before setArguments() will throw "Typed property must not be accessed before initialization". Initialize it to an empty array (e.g., default [] on the property or set it in the constructor).

Suggested change

private array $arguments;

private array $arguments = [];

Copilot · 2026-04-03T14:35:45Z

Slim/Middleware/RoutingMiddleware.php

+        $requestPath = $request->getUri()->getPath();
+        $basePath = $this->router->getBasePath();
+        $dispatchPath = $this->stripBasePath($requestPath, $this->router->getBasePath());

-        $httpMethod = $request->getMethod();
-        $uri = $request->getUri()->getPath();
+        $routingResult = $this->dispatcher->dispatch(
+            $request->getMethod(),
+            rawurldecode($dispatchPath)
+        );

-        // Determine base path
-        $basePath = $request->getAttribute(RouteContext::BASE_PATH) ?? $this->router->getBasePath();
+        $routeMatch = $this->createRouteMatch($routingResult, $basePath);
+        $request = $request->withAttribute(RouteMatch::class, $routeMatch);
+
+        return $handler->handle($request);
+    }
+
+    /**
+     * @param array<int, mixed> $routingResult
+     */
+    private function createRouteMatch(array $routingResult, string $basePath): RouteMatch
+    {
+        $status = $routingResult[0] ?? null;
+
+        return match ($status) {
+            DispatcherInterface::FOUND => RouteMatch::found(
+                $this->assertRoute($routingResult[1] ?? null),
+                $this->extractArguments($routingResult[2] ?? null),
+            ),
+            DispatcherInterface::METHOD_NOT_ALLOWED => RouteMatch::methodNotAllowed(
+                $this->extractAllowedMethods($routingResult[1] ?? null),
+            ),
+            DispatcherInterface::NOT_FOUND => RouteMatch::notFound(),
+            default => throw new RuntimeException('Invalid routing result status returned by dispatcher.'),
+        };


createRouteMatch() takes $basePath, but the value is never used inside the method (and the caller computes/passes it anyway). Either remove this parameter (and related $basePath local) or incorporate base path into the routing result object if that’s still required by the new design.

Copilot · 2026-04-03T14:35:46Z

Slim/Middleware/BasePathMiddleware.php

+        // $request = $request->withAttribute(RouteMatch::BASE_PATH_ATTRIBUTE, $basePath);



There’s a commented-out line referencing RouteMatch::BASE_PATH_ATTRIBUTE, but RouteMatch does not define that constant. Leaving dead/commented code with invalid identifiers makes the intent unclear—either remove this line or implement the attribute/constant as part of the new base-path strategy.

Suggested change

// $request = $request->withAttribute(RouteMatch::BASE_PATH_ATTRIBUTE, $basePath);

Copilot · 2026-04-03T14:35:46Z

tests/Routing/RouteMatchTest.php

+        $basePath = '/api';
+
+        $routeMatch = RouteMatch::notFound($basePath);
+


RouteMatch::notFound() is called with $basePath, but RouteMatch::notFound() is defined with no parameters. This test will fatal; either update the factory signature/implementation to accept base path (if intended) or remove the argument from the test.

Suggested change

$basePath = '/api';

$routeMatch = RouteMatch::notFound($basePath);

$routeMatch = RouteMatch::notFound();

Copilot · 2026-04-03T14:35:46Z

tests/Routing/RouteMatchTest.php

+        $basePath = '/api';
+
+        $routeMatch = RouteMatch::methodNotAllowed($allowedMethods, $basePath);


RouteMatch::methodNotAllowed() is called with ($allowedMethods, $basePath), but RouteMatch::methodNotAllowed() only accepts the allowed-methods array. This mismatch will fatal at runtime; align the test with the factory signature, or update RouteMatch if base path is meant to be carried in the match object.

Suggested change

$basePath = '/api';

$routeMatch = RouteMatch::methodNotAllowed($allowedMethods, $basePath);

$routeMatch = RouteMatch::methodNotAllowed($allowedMethods);

Copilot · 2026-04-03T14:35:46Z

tests/Middleware/RoutingMiddlewareTest.php

 use Slim\Middleware\RoutingMiddleware;
-use Slim\Routing\RouteContext;
+use Slim\Routing\RouteMatch;
 use Slim\Routing\RoutingResults;


use Slim\\Routing\\RoutingResults; is now unused and refers to a class removed by this PR. While it won’t autoload, it’s confusing and can cause IDE/static-analysis noise—please remove the import.

Suggested change

use Slim\Routing\RoutingResults;

Copilot · 2026-04-03T14:35:46Z

Slim/Interfaces/RouteInterface.php

+    /**
+     * Retrieve a specific route argument.
+     */
+    public function getArgument(string $name, ?string $default = null): ?string;
+
+    /**
+     * Get route arguments.
+     *
+     * @return array<string, string>
+     */
+    public function getArguments(): array;
+
+    /**
+     * Set route arguments.
+     *
+     * @param array<string,mixed> $arguments The arguments.
+     *
+     * @return RouteInterface
+     */
+    public function setArguments(array $arguments): RouteInterface;


The RouteInterface argument APIs are internally inconsistent: getArgument()/getArguments() are documented/typed as returning strings, but setArguments() documents array<string, mixed>. Either restrict setArguments() to array<string, string> (and enforce/validate) or widen the getters’ types/docs so callers aren’t misled.

Refactor routing architecture

24993e5

odan requested a review from Copilot April 3, 2026 14:31

odan merged commit 2f558e3 into slimphp:5.x Apr 3, 2026
6 of 7 checks passed

Copilot AI reviewed Apr 3, 2026

View reviewed changes

odan deleted the 5.x-route-arguments branch April 3, 2026 17:09

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

v5 - Refactor routing to use RouteMatch and dispatcher interfaces#3438

v5 - Refactor routing to use RouteMatch and dispatcher interfaces#3438
odan merged 1 commit intoslimphp:5.xfrom
odan:5.x-route-arguments

odan commented Apr 3, 2026

Uh oh!

coveralls commented Apr 3, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		// $request = $request->withAttribute(RouteMatch::BASE_PATH_ATTRIBUTE, $basePath);

		$basePath = '/api';

		$routeMatch = RouteMatch::notFound($basePath);

		$basePath = '/api';

		$routeMatch = RouteMatch::methodNotAllowed($allowedMethods, $basePath);

Uh oh!

Conversation

odan commented Apr 3, 2026

Changes

Uh oh!

coveralls commented Apr 3, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants