Fast Route Laravel Package

Getting Started

Install FastRoute with composer require nikic/fast-route, ensuring you’re on PHP 8.1+. Begin by creating a simpleDispatcher with inline route definitions to quickly prototype routing logic. Start with a minimal HTTP application skeleton: extract $httpMethod and $uri from the request context (e.g., $_SERVER for web SAPI), strip the query string, decode the URI, then call $dispatcher->dispatch(). Use the returned status code (NOT_FOUND, METHOD_NOT_ALLOWED, or FOUND) to route control flow — for FOUND, invoke your handler (e.g., a callable, controller, or closure) with the captured parameters. This gives a fully working router in under 30 lines.

Implementation Patterns

Define all routes inside a closure passed to simpleDispatcher (development) or cachedDispatcher (production). Group related routes using addGroup() for cleaner organization (e.g., /api/v1, /admin). Leverage shorthand methods ($r->get(), $r->post(), etc.) to reduce boilerplate, and use named placeholders with regex constraints (e.g., {id:\d+}) for type-safe parameter extraction. Handlers can be strings (e.g., service names for a DI container), callables, invokables, or controller/action tuples — FastRoute only resolves the mapping. For complex routing, build reusable route collectors (e.g., per module) and merge them in the main dispatcher. Use cachedDispatcher in production to avoid rebuilding routing data on every request — configure cacheKey, and optionally cacheDriver (e.g., FileCache or custom PSR-6/16 implementation).

Gotchas and Tips

• HEAD fallback: FastRoute automatically routes HEAD to GET only if no explicit HEAD route exists — this may cause 405 if only HEAD is registered. Explicitly define HEAD routes when needed (e.g., for API endpoints).
• Optional segments: Must appear at the end of a route (e.g., /posts[{/id}] is invalid). Nested optionals like /user[/{id:\d+}[/{name}]] work but should be used sparingly to preserve readability.
• Capturing groups: Avoid ( and ) in placeholder patterns — use non-capturing (?:...) or pipe syntax ({lang:en|de}) to prevent regex conflicts.
• Routing cache busting: When using caching, change cacheKey (e.g., append app version) on route changes, or set cacheDisabled via environment variable (IS_DEBUG_ENABLED).
• Method not allowed: When returning 405, always include the Allow header from $routeInfo[1] — FastRoute provides it, but does not auto-include it in responses.
• Dispatcher caching: In cachedDispatcher, the cacheDriver can be a class name or instance — useful for injecting a PSR-6 cache pool. If overridden, ensure DataGenerator and Dispatcher implementations match (e.g., MarkBased ↔ MarkBased).