Routing Laravel Package

Getting Started

Begin by installing the package via Composer (composer require illuminate/routing). Since this is a subtree split of Laravel’s routing layer, it assumes Laravel’s ecosystem — even in standalone contexts. Start with bootstrapping the Router via Illuminate\Container\Container (e.g., $router = new Router($container = new Container)), then define and dispatch a route:

use Illuminate\Routing\Router;
use Illuminate\Http\Request;

$router = new Router($container = new Container);
$router->get('/ping', fn() => 'pong');

$request = Request::create('/ping', 'GET');
$response = $router->dispatch($request);
echo $response->getContent(); // "pong"

First explore Router and Route classes — they form the core API. Check RouteRegistrar for fluent route definition helpers (get(), post(), middleware(), etc.).

Implementation Patterns

• Route Grouping & DSL Chaining: Use $router->group(['prefix' => 'api'], fn() => $router->get('/users', ...)) to share attributes. Chain middleware(), name(), where(), and conditional() via the returned RouteRegistrar instance.
• Route Model Binding: Register explicit bindings with Route::bind('user', fn($slug) => User::where('slug', $slug)->first()), then use {user} in routes.
• Resourceful APIs: Define standard REST routes with $router->apiResource('posts', PostController::class) (or resource() for web routes).
• PSR Compatibility: Convert Symfony requests/responses to PSR-7 using symfony/psr-http-message-bridge — e.g., wrap incoming PSR-7 request via Psr16Bridge, dispatch through router, then convert response back.
• Middleware Stacks: Register middleware groups before route definition: $router->middlewareGroup('api', [ThrottleRequests::class]), then apply via ['middleware' => 'api'].

Gotchas and Tips

• Standalone Container Setup: You must provide a fully configured container (even for basic DI). Missing bindings (e.g., UrlGenerator, ResponseFactory) cause cryptic errors — pre-bind: $container->singleton(UrlGenerator::class, fn() => new UrlGenerator(...)).
• No Route Caching Tooling: Unlike Laravel, there’s no route:cache Artisan command. Implement your own caching layer using Route::collectRoutes()->getRoutesByName() and Route::compile() — or skip caching unless performance-critical.
• Middleware Timing Matters: Middleware registered after defining a route won’t affect that route. Always register global middleware ($router->middleware()) or route-specific middleware (->middleware(...)) before route definition.
• Debugging Route Resolution: Use $router->getRoutes()->get('GET', '/path') to verify route existence. Inside a closure, dd($router->getCurrentRoute()) helps diagnose mismatches.
• Test Isolation: In unit tests, avoid instantiating Router directly — use Laravel’s Tests\TestCase (which bootstraps the container) or mock Container and RequestStack precisely.
• Version Coupling: All illuminate/* dependencies must match Laravel 13. Upgrading one (e.g., illuminate/http) without others breaks routing. Lock versions strictly in composer.json.