Routing Laravel Package

Getting Started

Install the package via Composer: composer require nette/routing. Begin by instantiating a RouteList, typically in a dedicated routes.php file or service container definition. Define simple routes using addRoute() with pattern strings (e.g., 'posts/<id>') and controller/action references (e.g., 'Post:show') or closures. For request handling, inject the RouteList into your bootstrap and call $router->match($httpRequest)—this returns matched route parameters as an array (e.g., ['action' => 'show', 'id' => '123']) or null if no match. Start with basic static and parameterized routes before advancing to constraints and scoping.

Implementation Patterns

• Modular Route Organization: Use RouteList::withPath() to scope routes under prefixes (e.g., /api, /admin) or RouteList::withDomain() for subdomains. Group related routes by feature using separate RouteList instances composed via addList().
• Strict Parameter Constraints: Define validation via inline regex in route patterns (e.g., '<id:\d+>', '<slug:[\p{L}\p{N}_-]+>')—especially critical for public-facing URLs to prevent over-matching. Combine with defaults (e.g., '<action=default>') for optional segments.
• Bidirectional Consistency: Leverage constructUrl() with a parameter array to generate URLs and reuse those same patterns/defaults in addRoute(). This avoids discrepancies between outgoing links and inbound handling.
• PSR-7 Integration: In Laravel/Lumen apps, build middleware that runs $router->match($netteRequest), then constructs a PSR-7 ServerRequestInterface from matched parameters—ideal for migrating legacy Nette code or hybrid architectures.
• Route Flags for Debugging: Set custom flags on routes (->setFlags(['admin' => true])) and inspect them via getFlags() or getRoute()—useful for ACL checks or feature toggling in route processing.

Gotchas and Tips

• Order Matters: Routes are matched in insertion order; place more specific routes before generic ones (e.g., posts/<id> before posts/new). Use getRoutes() to inspect runtime ordering.
• Trailing Slash Ambiguity: Though withPath() treats trailing slashes as optional, manually define routes consistently (e.g., always posts/ or never posts) to prevent subtle redirect loops or 404s.
• PHP 8.2+ Requirement: v3.x requires PHP ≥8.2 (as of v3.1.0). If constrained to PHP 8.0/8.1, use nette/routing:^2.5 instead—check composer.json for exact version compatibility.
• RFC 3986 Encoding: Since v3.1.1, param2path() correctly handles RFC-compliant reserved characters (e.g., @, !, ~). Never pre-encode values passed to constructUrl()—it will double-encode.
• Default Value Pitfalls: Avoid non-stringable types (e.g., Closure, objects) as default parameter values unless using ≥v3.0.3—older versions throw exceptions when serializing defaults during URL building.
• Debugging Mismatches: Call Route::match($httpRequest) individually on specific routes (not the list) to isolate failing patterns. Use Route::getFlags() and Route::getPattern() to log effective route configurations.