## Getting Started

### Minimal Setup in Laravel
1. **Installation**:
   ```bash
   composer require symfony/routing:^8.1

Laravel already includes Symfony's routing under the hood, but this standalone package is useful for custom routing logic outside the framework's default router. Note: Version ^8.1 is now recommended to leverage new features and security fixes.

First Use Case: Define a route manually and generate URLs with the updated UrlGenerator:

use Symfony\Component\Routing\Route;
use Symfony\Component\Routing\RouteCollection;
use Symfony\Component\Routing\Generator\UrlGenerator;

$route = new Route('/blog/{slug}', [
    '_controller' => 'App\\Http\\Controllers\\BlogController@show',
]);
$routes = new RouteCollection();
$routes->add('blog_show', $route);

$generator = new UrlGenerator($routes);
$url = $generator->generate('blog_show', ['slug' => 'hello-world']);
// Outputs: "/blog/hello-world"

Where to Look First:
- Symfony Routing v8.1 Documentation (focus on "URL Generation" and "Security" sections).
- Laravel's Illuminate\Routing\Router (for integration patterns).
- Symfony Routing Changelog v8.1 for breaking changes.
- symfony/routing's source code for advanced use cases.

Implementation Patterns

1. Route Collections and Dynamic Loading

Pattern: Group routes logically (e.g., by module) and load them dynamically:

$routes = new RouteCollection();
$routes->addCollection($this->loadAdminRoutes());
$routes->addCollection($this->loadApiRoutes());

// Load from YAML/JSON/PHP files (Symfony's loaders)
$loader = new YamlFileLoader($routes, new FileLocator(__DIR__.'/config'));
$loader->load('routes.yaml');

New in 8.1: Use ContentLoaderTrait (now includes HostTrait) for host-based routing in custom loaders.

2. URL Generation in Controllers/Blades

Pattern: Generate URLs consistently across views and controllers:

// In a controller
$url = $generator->generate('blog_show', ['slug' => $post->slug], UrlGenerator::ABSOLUTE_URL);

// In Blade templates (pass generator to view)
<a href="{{ $url }}">Read Post</a>

Security Note: The UrlGenerator now validates regex requirements more strictly (see #cve-2026-45065).

3. Reverse Routing in Forms

Pattern: Use route names instead of hardcoded paths in forms:

$form->action = $generator->generate('user_edit', ['id' => $user->id]);

4. Custom Route Matching Logic

Pattern: Extend UrlMatcher for complex requirements (e.g., multi-tenancy):

$matcher = new UrlMatcher($routes, $context);
$parameters = $matcher->match('/api/v1/users/123');
$tenantId = $parameters['_tenant'] ?? null;

5. Integration with Laravel’s Router

Pattern: Use Symfony’s routing for non-HTTP routes (e.g., CLI commands or internal APIs):

$cliRoutes = new RouteCollection();
$cliRoutes->add('cli:backup', new Route('/backup', [], [], [], 'backup_command'));
$generator = new UrlGenerator($cliRoutes);
$command = $generator->generate('backup_command'); // Outputs: "/backup"

6. Route Requirements and Constraints

Pattern: Validate route parameters early with stricter regex handling:

$route = new Route('/user/{id}', [], [], [], [], ['id' => '\d+']);
$matcher = new UrlMatcher([$route], $context);
$matcher->match('/user/123'); // Valid
$matcher->match('/user/abc'); // Throws Exception (now more secure)

Fix for CVE-2026-45065: Ensure regex alternations (e.g., a|b) are properly anchored to avoid injection risks.

7. Localization and Route Prefixes

Pattern: Handle multi-language routes with HostTrait (now included in ContentLoaderTrait):

$route = new Route('/{_locale}/blog/{slug}', [
    '_locale' => 'en|fr',
]);
$context = new RequestContext();
$context->setParameter('_locale', 'fr');
$generator->generate('blog_show', ['slug' => 'bonjour'], [], UrlGenerator::ABSOLUTE_PATH);
// Outputs: "/fr/blog/bonjour"

Gotchas and Tips

Pitfalls

Case Sensitivity in Host Matching:
- Host-based routes (e.g., api.example.com) are case-sensitive. Use HostTrait (now part of ContentLoaderTrait) or compile routes with case-insensitive flags.
- Fix: Update RequestContext or use Route::setHost() with lowercase hosts.
Query Parameters in URL Generation:
- Query parameters (?_query=value) are not preserved by default. Use the _query option explicitly:
```
$generator->generate('route_name', [], ['_query' => ['sort' => 'asc']]);
```
Circular Route References:
- Avoid infinite loops in redirects. Use UrlGenerator::ABSOLUTE_URL or validate routes before generation.
Parameter Overwriting:
- Default route parameters can be overwritten. Use UrlGenerator::INCLUDE_DEFAULT_VALUES:
```
$generator->generate('route_name', [], UrlGenerator::INCLUDE_DEFAULT_VALUES);
```

Performance with Large Route Collections:

Compile routes for production:

$compiler = new RouteCompiler();
$compiledRoutes = $compiler->compile($routes);
$matcher = new CompiledUrlMatcher($compiledRoutes, $context);

Regex Requirement Validation (New in 8.1):
- Security Risk: Malicious regex patterns (e.g., a|.*) can cause performance issues or injection. Fix:
  - Anchor alternations: Use ^(a|b)$ instead of a|b.
  - Validate requirements in tests:
```
$this->assertTrue(preg_match('/^\d+$/', '123')); // Safe
$this->assertFalse(preg_match('/.*/', 'malicious')); // Rejected
```

Debugging Tips

Inspect Matched Parameters:

Log UrlMatcher::match() output:

try {
    $params = $matcher->match('/some/path');
} catch (Exception $e) {
    logger()->error('Route match failed:', ['exception' => $e, 'path' => '/some/path']);
}

Validate Route Definitions:

Use RouteCollection::getIterator() to validate routes:

foreach ($routes as $name => $route) {
    if (empty($route->getDefault('_controller'))) {
        logger()->warning("Route '$name' has no controller!");
    }
}

Test URL Generation:

Write unit tests for critical routes:

public function testUrlGeneration()
{
    $this->assertEquals(
        '/blog/hello-world',
        $generator->generate('blog_show', ['slug' => 'hello-world'])
    );
}

Extension Points

Custom Route Loaders:

Extend FileLocator or RouteLoaderInterface to load routes from custom sources (e.g., databases):

class DatabaseRouteLoader implements RouteLoaderInterface
{
    public function load($resource, string $type = null)
    {
        $routes = $this->fetchRoutesFromDatabase();
        return new RouteCollection($routes);
    }
}

New in 8.1: Leverage ContentLoaderTrait for host-based routing in custom loaders.

Middleware for Route Matching:

Wrap UrlMatcher in middleware:

$matcher = new UrlMatcher($routes, $context);
$matcher = new CustomMatcherDecorator($matcher);

class CustomMatcherDecorator
{
    public function match(string $pathinfo): array
    {
        $start = microtime(true);

Routing Laravel Package