Routing Laravel Package

Getting Started

Minimal Setup in Laravel

Leverage Symfony's Routing component in Laravel via the built-in Illuminate/Routing facade, which internally uses Symfony's Routing component. No direct composer require is needed—it's a core dependency.

First Use Case: Define a Route

use Illuminate\Support\Facades\Route;

// Basic route definition (uses Symfony's Route class under the hood)
Route::get('/blog/{slug}', [BlogController::class, 'show'])
    ->name('blog.show');

Key Entry Points:

1. Route Facade: Laravel's wrapper for Symfony's RouteCollection.
2. UrlGenerator: Access via route() helper or Illuminate\Routing\Router.
3. UrlMatcher: Used internally by Laravel's middleware and controllers.

Quick Test:

// Generate a URL
$url = route('blog.show', ['slug' => 'hello-world']);

// Match a request (simulate middleware logic)
$parameters = app('router')->getRoutes()->match(app('request')->create('/blog/hello-world'));

Implementation Patterns

1. Route Configuration

YAML/Array Syntax (Laravel's routes/web.php):

Route::get('/user/{id}', function ($id) {
    // ...
})->name('user.profile');

// Equivalent Symfony Route object:
$route = new \Symfony\Component\Routing\Route(
    '/user/{id}',
    ['_controller' => fn($id) => '...'],
    ['id' => '\d+'] // Requirements
);

Dynamic Routes with Attributes (Laravel 8+):

use Symfony\Component\Routing\Annotation\Route;

class BlogController {
    #[Route('/posts/{slug}', name: 'posts.show')]
    public function show(string $slug) { ... }
}

2. URL Generation

Basic Usage:

// Absolute URL
$url = route('blog.show', ['slug' => 'post'], false);

// Relative URL (e.g., for redirects)
$url = route('blog.show', ['slug' => 'post'], true);

Query Parameters:

$url = route('blog.show', [
    'slug' => 'post',
    '_query' => ['sort' => 'desc', 'page' => 1] // Symfony 6.0+ feature
]);

3. Request Matching

Middleware/Event Logic:

use Symfony\Component\HttpFoundation\Request;

public function handle(Request $request, Closure $next) {
    $parameters = app('router')->getRoutes()->match($request);
    // Custom logic using $parameters['_route'], $parameters['slug'], etc.
    return $next($request);
}

4. Route Groups

Route::prefix('admin')->group(function () {
    Route::get('/users', [UserController::class, 'index']);
    // All routes here inherit `/admin` prefix.
});

5. Route Caching

Laravel auto-caches routes in bootstrap/cache/routes.php. Clear with:

php artisan route:clear

Gotchas and Tips

Pitfalls

1. Case Sensitivity in Host Matching

   • Symfony 8+ enforces case-sensitive host matching by default. Use host: '~^(?-i:example\.com)$~' in YAML or hostRegex: '/^(?-i:example\.com)$/' in PHP for case-insensitive matching.

2. Numeric Query Parameters

   • Avoid numeric keys in _query parameters (e.g., ['page' => 1] works; [0 => 'page'] fails). Use associative arrays.

3. Route Overrides

   • Laravel’s RouteServiceProvider merges routes from multiple files. Overrides are last-in-wins. Use Route::priority() to control precedence.

4. Attribute Routes in Namespaces

   • Ensure #[Route] attributes are imported correctly:

     use Symfony\Component\Routing\Annotation\Route;
     

5. Circular Dependencies in Route Loading

   • Avoid circular references in route definitions (e.g., Route A referencing Route B which references Route A).

Debugging Tips

1. Dump Route Parameters

   dd(app('router')->getRoutes()->get('blog.show')->compile()->getVariables());
   

2. Check Matched Route

   $request = app('request');
   dd(app('router')->getRoutes()->match($request));
   

3. Validate Route Existence

   if (!app('router')->getRoutes()->get('non.existent')) {
       abort(404);
   }
   

4. Clear Route Cache

   php artisan route:clear
   php artisan optimize:clear
   

Extension Points

1. Custom Route Compiler Extend Symfony\Component\Routing\RouteCompiler to add logic (e.g., custom requirements):

   use Symfony\Component\Routing\RouteCompilerInterface;
   
   class CustomRouteCompiler implements RouteCompilerInterface {
       public function compile(RouteCollection $routes) {
           // Custom logic
           return new CompiledRouteCollection($routes);
       }
   }
   

2. Route Loaders Implement Symfony\Component\Routing\Loader\LoaderInterface for custom formats (e.g., JSON):

   class JsonRouteLoader implements LoaderInterface {
       public function load(string $resource, string $type = null) {
           return new RouteCollection(json_decode(file_get_contents($resource), true));
       }
   }
   

3. Middleware Integration Use Symfony\Component\HttpKernel\Event\RequestEvent to inspect routes:

   public function onKernelRequest(RequestEvent $event) {
       $request = $event->getRequest();
       $parameters = app('router')->getRoutes()->match($request);
       // ...
   }
   

4. Route Model Binding Laravel’s implicit model binding relies on Symfony’s Route requirements:

   Route::get('/posts/{post}', [PostController::class, 'show'])
       ->where('post', '[0-9]+'); // Ensures binding to Post::find($post)
   

Performance Quirks

1. Avoid Dynamic Route Requirements Compile-time requirements (e.g., regex) are faster than runtime checks.

2. Cache Route Collections Laravel caches routes by default. Disable with:

   'route.cache' => false,
   

   in config/cache.php.

3. Use Route::getRoutes() Sparingly Accessing app('router')->getRoutes() triggers compilation. Cache the result if reused:

   $routes = app('router')->getRoutes();
   // Reuse $routes instead of calling getRoutes() repeatedly.