Router Laravel Package

Getting Started

Install the package via Composer: composer require joomla/router "~3.0" (v3.x requires PHP 8.1+, v4.x requires PHP 8.3+). Begin by instantiating Joomla\Router\Router, then register routes using addRoute() with HTTP method, pattern (including named placeholders like :id), and a callable target (controller class/method, closure, or callable string). Use parseRoute($uri) to match a path and extract matched variables. The simplest first use case is mapping REST-style endpoints to controller methods, e.g.:

$router = new Router();
$router->addRoute('GET', '/api/users/:id', 'App\Controller\UserController@show', ['id' => '\d+']);
$match = $router->parseRoute('/api/users/123');
// $match->getController() and $match->getVariables() provide structured access (v2+)

Start with the README and docs/overview.md—they contain core examples and clarify that the package only handles routing logic; controller execution remains your responsibility.

Implementation Patterns

• Pattern matching with regex constraints: Leverage the third parameter of addRoute() to enforce type-specific variables (e.g., ['id' => '\d+'] for IDs), ensuring cleaner validation upstream.
• Default variables for context injection: Use the optional fifth parameter of addRoute() to inject non-path-based data (e.g., 'requires_auth' => true, 'version' => 'v2') into the resolved route via the defaults array—accessible through ResolvedRoute::getDefaults() in v2+.
• Command-line debugging: When using joomla/console, add DebugRouterCommand to list all configured routes, helpful for introspecting API endpoints during development.
• Front controller integration: In micro-framework setups, pair parseRoute() with dynamic controller dispatch, e.g., $controller = new $route->getController(); $controller->handle($route->getVariables());, or use call_user_func_array() for lightweight setups.
• Method-specific routing: Always specify HTTP methods (GET, POST, etc.) when adding routes to avoid accidental cross-method dispatch. Match patterns like /resource/:id only for reads, and /resource for collections.

Gotchas and Tips

• Breaking change in v2+: parseRoute() now returns a ResolvedRoute object, not an array—access via getController(), getVariables(), and getDefaults() instead of array indexing.
• Default regex behavior: Named placeholders default to ([^/]*); be explicit about regex when matching non-string types (e.g., integers) to avoid malformed matches.
• Closure serialization caveats: Though closures are supported, avoid capturing large state or database connections in them if the router may be serialized (e.g., in caching scenarios). Prefer controller classes or named callables for production.
• Case sensitivity: Route paths are case-sensitive; normalize URIs (e.g., via strtolower()) before parsing if case-insensitivity is required.
• Maturity signal: With only 8 stars and low community adoption, expect minimal third-party ecosystem support. Prefer this package only for lightweight internal tools where tight integration with Joomla console is beneficial—don’t use for public-facing APIs without heavy testing.
• PHP 8.3+ requirement in v4: Ensure your environment matches the release version’s minimum—v3 uses PHP 8.1+, but v4+ (current 3.x-dev and newer) requires PHP 8.3.