Symfony Routing

https://github.com/symfony/routing
Admin
Symfony Routing is a highly flexible PHP library that maps an incoming HTTP request to a set of...
Tokens:109,999
Snippets:796
Trust Score:9.5
License:MIT
Update:2 days ago
Show doc for...
Tokens:
Raw
### RouterMatchCommand usage examples

Source: https://github.com/symfony/routing

Shows how to invoke the router:match command with different options. The first example matches a path, the second specifies method, scheme, host, and verbose output.

```bash
bin/console router:match /blog/foo
bin/console router:match /foo --method POST --scheme https --host symfony.com --verbose
```

--------------------------------

### RouterCacheWarmer usage example

Source: https://github.com/symfony/routing

Shows how to instantiate RouterCacheWarmer and call warmUp(). The example returns an array of compiled URL generator and matcher classes.

```php
use Symfony\Component\Routing\CacheWarmer\RouterCacheWarmer;

$warmer = new RouterCacheWarmer($container);
$classes = $warmer->warmUp('/var/cache/app', '/var/cache/app'); 
// returns ['Symfony\Component\Routing\Generator\CompiledUrlGenerator', 'Symfony\Component\Routing\Matcher\CompiledUrlMatcher']
```

--------------------------------

### Full usage example with data and code forms

Source: https://github.com/symfony/routing

Complete example showing both data form (getCompiledRoutes/getCompiledAliases) and code form (dump) usage.

```php
use Symfony\Component\Routing\Generator\Dumper\CompiledUrlGeneratorDumper;
use Symfony\Component\Routing\Generator\CompiledUrlGenerator;
use Symfony\Component\Routing\RequestContext;

$dumper = new CompiledUrlGeneratorDumper($routes);

// data form (no code generation)
$compiled = array_merge($dumper->getCompiledRoutes(), $dumper->getCompiledAliases());

// code form (for cache files)
$code = $dumper->dump();

$generator = new CompiledUrlGenerator($compiled, new RequestContext());
```

--------------------------------

### Match result example

Source: https://github.com/symfony/routing

Example of the array returned by match() or matchRequest(): merged route defaults, matched variables, and the _route key.

```php
['_controller' => 'App\Controller\BlogController::show', 'slug' => 'lorem-ipsum', '_route' => 'blog_show']
```

--------------------------------

### Install Symfony Routing with Composer

Source: https://github.com/symfony/routing/blob/8.2/README.md

Use Composer to install the symfony/routing package.

```bash
composer require symfony/routing
```

--------------------------------

### CompiledUrlMatcherDumper dump() output example

Source: https://github.com/symfony/routing

Example of the PHP code returned by dump(), showing the auto-generated header and the return array placeholder for compiled routes.

```php
<?php

/**
 * This file has been auto-generated
 * by the Symfony Routing Component.
 */

return [
<compiled routes>
];
```

--------------------------------

### Usage examples for urlRedirectAction()

Source: https://github.com/symfony/routing

Two usage examples: a 301 redirect to an absolute path with permanent: true, and a redirect to a full URL. The first keeps the query string; the second returns the URL as-is.

```php
// 301 redirect to an absolute path, keeping query string
$response = $controller->urlRedirectAction($request, '/new/location', permanent: true);

// redirect to a full URL
$response = $controller->urlRedirectAction($request, 'https://example.com/elsewhere');
```

--------------------------------

### Router constructor options example

Source: https://github.com/symfony/routing

Shows how to instantiate the Router with a custom options array. The options include cache_dir, debug, strict_requirements, and matcher_class. Unknown keys throw an InvalidArgumentException.

```php
$router = new Router($loader, 'routes.yaml', [
    'cache_dir' => __DIR__.'/var/cache/routing',
    'debug' => true,
    'strict_requirements' => null,
    'matcher_class' => RedirectableCompiledUrlMatcher::class,
]);
```

--------------------------------

### Example PHP routing file using RoutingConfigurator

Source: https://github.com/symfony/routing

Demonstrates defining routes with add(), importing resources, and grouping routes via collection().

```php
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return function (RoutingConfigurator $routes): void {
    $routes->add('blog_show', '/blog/{slug}')
        ->controller('App\Controller\BlogController::show')
        ->requirements(['slug' => '[a-z0-9-]+'])
        ->methods(['GET']);

    $routes->import('admin.yaml')
        ->prefix('/admin')
        ->namePrefix('admin_');

    $routes->collection('api')
        ->prefix('/api')
        ->add('users', '/users');
};
```

--------------------------------

### Using CompiledUrlMatcherDumper to generate cache file

Source: https://github.com/symfony/routing

Shows how to instantiate the dumper, get compiled routes, and persist the dump to a cache file that returns the compiled array.

```php
use Symfony\Component\Routing\Matcher\Dumper\CompiledUrlMatcherDumper;

$dumper = new CompiledUrlMatcherDumper($routes);
$compiled = $dumper->getCompiledRoutes();

// persist the dump to a cache file that returns the compiled array
file_put_contents('/var/cache/url_matching_routes.php', $dumper->dump());
```

--------------------------------

### Example routes.php file

Source: https://github.com/symfony/routing

Shows a PHP file that returns a callable receiving a RoutingConfigurator. The callable adds a route named 'blog_show' for '/blog/{slug}' with a controller and requirements.

```php
// routes.php
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return function (RoutingConfigurator $routes): void {
    $routes->add('blog_show', '/blog/{slug}')
        ->controller('App\Controller\BlogController::show')
        ->requirements(['slug' => '[a-z0-9-]+']);
};
```

--------------------------------

### runWith() usage example with UrlGenerator

Source: https://github.com/symfony/routing

Shows how to use runWith() to generate a URL with temporary scheme and host values. The context is restored to its original state after the callback, even if the callback throws.

```php
use Symfony\Component\Routing\RequestContext;
use Symfony\Component\Routing\Generator\UrlGenerator;

$context = new RequestContext();
$generator = new UrlGenerator($routes, $context);

$url = $context->runWith(
    fn () => $generator->generate('blog_show', ['slug' => 'x']),
    scheme: 'https',
    host: 'symfony.com',
);

// context is back to its original state afterwards
```

--------------------------------

### YAML route definition example

Source: https://github.com/symfony/routing

Example YAML routing file defining a route named blog_show with a path, controller, and requirements. The slug requirement uses a regular expression pattern.

```yaml
# routes.yaml
blog_show:
    path: /blog/{slug}
    controller: App\Controller\BlogController::show
    requirements:
        slug: '[a-z0-9-]+'
```

--------------------------------

### Basic usage of UrlMatcher::match()

Source: https://github.com/symfony/routing

Example of creating a RouteCollection, adding a route, and using UrlMatcher to match a path. The match returns route parameters including defaults and '_route'.

```php
use Symfony\Component\Routing\Matcher\UrlMatcher;
use Symfony\Component\Routing\RequestContext;
use Symfony\Component\Routing\Route;
use Symfony\Component\Routing\RouteCollection;

$routes = new RouteCollection();
$routes->add('blog_show', new Route(
    '/blog/{slug}',
    ['_controller' => 'App\Blog::show'],
    methods: ['GET']
));

$matcher = new UrlMatcher($routes, new RequestContext(method: 'GET'));
$params = $matcher->match('/blog/lorem-ipsum');
// ['_controller' => 'App\Blog::show', 'slug' => 'lorem-ipsum', '_route' => 'blog_show']
```

--------------------------------

### Using CompiledUrlGeneratorDumper with cache file

Source: https://github.com/symfony/routing

Example showing how to dump compiled routes to a cache file and consume them at runtime with CompiledUrlGenerator.

```php
use Symfony\Component\Routing\Generator\CompiledUrlGenerator;
use Symfony\Component\Routing\Generator\Dumper\CompiledUrlGeneratorDumper;

$dumper = new CompiledUrlGeneratorDumper($routes);
$compiledRoutes = array_merge($dumper->getCompiledRoutes(), $dumper->getCompiledAliases());

// persist for later use
file_put_contents('/var/cache/url_generating_routes.php', $dumper->dump());

// consume at runtime
$generator = new CompiledUrlGenerator(require '/var/cache/url_generating_routes.php', $context);
$url = $generator->generate('blog_show', ['slug' => 'hello']);
```

--------------------------------

### RedirectController usage example

Source: https://github.com/symfony/routing

Shows how to instantiate RedirectController and call redirectAction() for a temporary (302) redirect and a permanent (301) redirect that preserves the HTTP method (308).

```php
use Symfony\Component\Routing\Controller\RedirectController;

$controller = new RedirectController($router);

// 302 redirect to the 'blog_show' route, forwarding current route params
$response = $controller->redirectAction($request, 'blog_show');

// permanent (301), keep the HTTP method (308)
$response = $controller->redirectAction($request, 'blog_show', permanent: true, keepRequestMethod: true);
```

--------------------------------

### Compiling a route with RouteCompiler

Source: https://github.com/symfony/routing

Example of compiling a route with a placeholder and default format. `getVariables()` returns `['slug', '_format']` and `getStaticPrefix()` returns `'/article'`.

```php
use Symfony\Component\Routing\Route;
use Symfony\Component\Routing\RouteCompiler;

$compiled = RouteCompiler::compile(new Route('/article/{slug}.{_format}', ['_format' => 'html']));

$vars = $compiled->getVariables();            // ['slug', '_format']
$prefix = $compiled->getStaticPrefix();       // '/article'
```

--------------------------------

### RouteCollection usage example

Source: https://github.com/symfony/routing

Shows how to add routes with priorities and iterate over them. Routes are ordered by priority (higher first), so 'blog_show' comes before 'blog_index'.

```php
use Symfony\Component\Routing\Route;
use Symfony\Component\Routing\RouteCollection;
use Symfony\Component\Routing\Generator\UrlGenerator;
use Symfony\Component\Routing\RequestContext;

$routes = new RouteCollection();
$routes->add('blog_index', new Route('/blog'), 5);
$routes->add('blog_show', new Route('/blog/{slug}'), 10);

// higher priority first
foreach ($routes as $name => $route) {
    // 'blog_show' first, then 'blog_index'
}
```

--------------------------------

### Route condition usage example

Source: https://github.com/symfony/routing

Example showing how addCondition() combines conditions. The output is "(request.isSecure()) and (params[\"id\"] > 10)".

```php
$route = new Route('/secure', condition: 'request.isSecure()');
$route->addCondition('params["id"] > 10');
echo $route->getCondition();
// "(request.isSecure()) and (params[\"id\"] > 10)"
```

--------------------------------

### Route and Import Definitions in YAML (config/routes.yaml)

Source: https://github.com/symfony/routing

Example YAML route file showing an import definition with directory type, a route definition with controller and requirements, and a deprecated alias. The `admin` import uses `resource`, `type`, `prefix`, `name_prefix`, and `defaults`. The `blog_show` route defines `path`, `controller`, `requirements`, and `methods`. The `legacy_blog` alias uses `deprecated` with `package`, `version`, and `message`.

```yaml
# config/routes.yaml
admin:
    resource: 'admin/'
    type: directory
    prefix: /admin
    name_prefix: admin_
    defaults: { _locale: en }

blog_show:
    path: /blog/{slug}
    controller: App\Controller\BlogController::show
    requirements:
        slug: '[a-z0-9-]+'
    methods: [GET]

legacy_blog:
    alias: blog_show
    deprecated:
        package: acme/blog
        version: '2.0'
        message: 'Use "blog_show" instead (alias "%alias_id%").'
```

--------------------------------

### Using TraceableUrlMatcher to Trace Routes

Source: https://github.com/symfony/routing

Example of creating a TraceableUrlMatcher with routes and context, then iterating over traces for a path. Each trace prints the route name, level, and log message. Useful for debugging why routes match or fail.

```php
use Symfony\Component\Routing\Matcher\TraceableUrlMatcher;

$matcher = new TraceableUrlMatcher($routes, $context);

foreach ($matcher->getTraces('/blog/foo') as $trace) {
    printf('%s (%s): %s', $trace['name'], $trace['level'], $trace['log']);
}
```

--------------------------------

### getRelativePath() static method signature

Source: https://github.com/symfony/routing

Returns the target path as a relative reference from the base path. Both paths must be absolute paths (no scheme/host) starting with `/`. Examples: base `/a/b/c/d` → target `/a/b/c/d` gives `''`; `/a/b/c/` gives `'./'`; `/a/b/` gives `'../'`; `/a/b/c/other` gives `'other'`; `/a/x/y` gives `'../../x/y'`.

```php
public static function getRelativePath(string $basePath, string $targetPath): string
```

--------------------------------

### Route attribute usage example

Source: https://github.com/symfony/routing

Shows how to apply the Route attribute to a controller class and its methods, including localized paths and method-specific configurations.

```php
use Symfony\Component\Routing\Attribute\Route;

#[Route('/blog', name: 'blog', host: 'example.com')]
class BlogController
{
    #[Route('/{slug}', name: 'blog_show', methods: ['GET'], requirements: ['slug' => '[a-z0-9-]+'])]
    public function show(string $slug): Response { /* … */ }

    #[Route(['en' => '/about', 'fr' => '/a-propos'], name: 'about')]
    public function about(): Response { /* … */ }
}
```

--------------------------------

### RouteCompiler::compile usage example

Source: https://github.com/symfony/routing

Example of using RouteCompiler::compile to compile a route and access the compiled data.

```APIDOC
## [EXAMPLE] RouteCompiler::compile usage

### Description
Example of using RouteCompiler::compile to compile a route and access the compiled data.

### Code
```php
use Symfony\Component\Routing\Route;
use Symfony\Component\Routing\RouteCompiler;

$compiled = RouteCompiler::compile(new Route('/article/{slug}.{_format}', ['_format' => 'html']));

$vars = $compiled->getVariables();            // ['slug', '_format']
$prefix = $compiled->getStaticPrefix();       // '/article'
```
```

--------------------------------

### Usage example (combined flow)

Source: https://github.com/symfony/routing

Shows how to combine AttributeRouteControllerLoader and AttributeDirectoryLoader to load routes from a directory. The directory loader uses a FileLocator and the controller loader to process PHP files in the given path.

```php
use Symfony\Component\Config\FileLocator;
use Symfony\Component\Routing\Loader\AttributeDirectoryLoader;
use Symfony\Component\Routing\Loader\AttributeRouteControllerLoader;

$controllerLoader = new AttributeRouteControllerLoader();
$directoryLoader = new AttributeDirectoryLoader(new FileLocator([__DIR__]), $controllerLoader);

$routes = $directoryLoader->load(__DIR__.'/src/Controller', 'attribute');
```

--------------------------------

### ClosureLoader usage example

Source: https://github.com/symfony/routing

Example of using ClosureLoader to load a route collection from a closure. The closure creates a new RouteCollection and adds a route named 'home' with path '/'.

```php
$routes = $loader->load(function (): RouteCollection {
    $collection = new RouteCollection();
    $collection->add('home', new Route('/'));
    return $collection;
});
```

--------------------------------

### setContext() / getContext() method signatures

Source: https://github.com/symfony/routing

Signatures for setting and getting the RequestContext in UrlGenerator.

```php
public function setContext(RequestContext $context): void
public function getContext(): RequestContext
```

--------------------------------

### Routes::config() usage

Source: https://github.com/symfony/routing

Shows how to use Routes::config() in a routing file to define routes with array configuration. The example defines a 'controllers' import with resource 'routing.controllers'.

```php
namespace Symfony\Component\Routing\Loader\Configurator;

return Routes::config([
    'controllers' => [
        'resource' => 'routing.controllers',
    ],
]);
```

--------------------------------

### Using addPrefix() and addNamePrefix()

Source: https://github.com/symfony/routing

Example of adding a prefix to all routes and prefixing route names. The comment shows that route 'dashboard' becomes 'admin_dashboard' on path '/admin/dashboard'.

```php
$routes->addPrefix('/admin', ['_locale' => 'en'], ['_locale' => 'en|fr']);
$routes->addNamePrefix('admin_');
// route "dashboard" becomes "admin_dashboard" on path "/admin/dashboard"
```

--------------------------------

### Adding routes with RouteCollection::add()

Source: https://github.com/symfony/routing

Example of creating a RouteCollection and adding two routes with priorities. The 'blog_show' route has priority 10, so it will be ordered before 'homepage'.

```php
use Symfony\Component\Routing\Route;
use Symfony\Component\Routing\RouteCollection;

$routes = new RouteCollection();
$routes->add('blog_show', new Route('/blog/{slug}'), priority: 10);
$routes->add('homepage', new Route('/'));
```

--------------------------------

### Invokable RedirectController usage example

Source: https://github.com/symfony/routing

Example of invoking the controller directly with a request, using the invokable form. The routing config defaults include `_controller: Symfony\Component\Routing\Controller\RedirectController`, `path: /new`, and `permanent: true`.

```php
// routing config using the invokable form
//   defaults: { _controller: Symfony\Component\Routing\Controller\RedirectController, path: /new, permanent: true }
$response = $controller($request);
```

--------------------------------

### AsRoutingConditionService usage example

Source: https://github.com/symfony/routing

Shows a service class marked with #[AsRoutingConditionService('foo')] and a method bar() returning a boolean. The service is then available in route conditions via the service() function.

```php
use Symfony\Component\Routing\Attribute\AsRoutingConditionService;

#[AsRoutingConditionService('foo')]
class SomeFooService
{
    public function bar(): bool
    {
        // …
    }
}
```

--------------------------------

### RequestContext::fromUri() usage example

Source: https://github.com/symfony/routing

Creates a context from a URI with a custom port. The resulting context has host 'symfony.com', scheme 'https', httpsPort 8443, and baseUrl '/admin'.

```php
use Symfony\Component\Routing\RequestContext;

$context = RequestContext::fromUri('https://symfony.com:8443/admin?page=2');
// host 'symfony.com', scheme 'https', httpsPort 8443, baseUrl '/admin'
```

--------------------------------

### AttributeRouteControllerLoader usage example

Source: https://github.com/symfony/routing

Shows how to load routes from a controller class using AttributeRouteControllerLoader. The controller uses the #[Route] attribute; the loader creates a route named 'blog_show' with _controller set to 'App\Controller\BlogController::show'.

```php
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Routing\Loader\AttributeRouteControllerLoader;

#[Route('/blog')]
class BlogController
{
    #[Route('/{slug}', name: 'blog_show', requirements: ['slug' => '[a-z0-9-]+'])]
    public function show(string $slug): Response { /* … */ }
}

$loader = new AttributeRouteControllerLoader(env: 'prod');
$collection = $loader->load(BlogController::class);
// route "blog_show" with _controller "App\Controller\BlogController::show"
```

--------------------------------

### AsRouteLoader usage example

Source: https://github.com/symfony/routing

Shows a service class marked with #[AsRouteLoader] and a loadRoutes() method returning a RouteCollection. The service can then be referenced in routing resources.

```php
use Symfony\Component\Routing\Attribute\AsRouteLoader;
use Symfony\Component\Routing\RouteCollection;

#[AsRouteLoader]
class SomeRouteLoader
{
    public function loadRoutes(): RouteCollection
    {
        // …
    }
}
```

--------------------------------

### Compile a route with RouteCompiler

Source: https://github.com/symfony/routing

Example of compiling a route with a slug variable and custom requirement. The compiled route's static prefix is '/blog' and the regex is '{^/blog/(?P<slug>[a-z0-9-]+)$}sD'.

```php
use Symfony\Component\Routing\Route;
use Symfony\Component\Routing\RouteCompiler;

$route = new Route('/blog/{slug<\w+>}', ['_controller' => 'App\Blog::show'], ['slug' => '[a-z0-9-]+']);
$compiled = RouteCompiler::compile($route);

echo $compiled->getStaticPrefix(); // '/blog'
echo $compiled->getRegex();        // '{^/blog/(?P<slug>[a-z0-9-]+)$}sD'
```

--------------------------------

### Match and Generate URLs with Symfony Routing

Source: https://github.com/symfony/routing/blob/8.2/README.md

Create a route, add it to a collection, and use UrlMatcher to match an incoming request and UrlGenerator to generate a URL. The example shows the expected output for both operations.

```php
use App\Controller\BlogController;
use Symfony\Component\Routing\Generator\UrlGenerator;
use Symfony\Component\Routing\Matcher\UrlMatcher;
use Symfony\Component\Routing\RequestContext;
use Symfony\Component\Routing\Route;
use Symfony\Component\Routing\RouteCollection;

$route = new Route('/blog/{slug}', ['_controller' => BlogController::class]);
$routes = new RouteCollection();
$routes->add('blog_show', $route);

$context = new RequestContext();

// Routing can match routes with incoming requests
$matcher = new UrlMatcher($routes, $context);
$parameters = $matcher->match('/blog/lorem-ipsum');
// $parameters = [
//     '_controller' => 'App\Controller\BlogController',
//     'slug' => 'lorem-ipsum',
//     '_route' => 'blog_show'
// ]

// Routing can also generate URLs for a given route
$generator = new UrlGenerator($routes, $context);
$url = $generator->generate('blog_show', [
    'slug' => 'my-blog-post',
]);
// $url = '/blog/my-blog-post'
```

--------------------------------

### Catch MethodNotAllowedException and get allowed methods

Source: https://github.com/symfony/routing

Use this snippet to handle a POST request when the route only allows GET. The exception's getAllowedMethods() returns the HTTP methods that would have been allowed, e.g., ['GET'].

```php
use Symfony\Component\Routing\Exception\MethodNotAllowedException;

try {
    $matcher->match('/blog/1'); // POST request, route allows GET
} catch (MethodNotAllowedException $e) {
    $allowed = $e->getAllowedMethods(); // ['GET']
}
```

--------------------------------

### Route::__construct() and UrlMatcher::match()

Source: https://github.com/symfony/routing

Shows how to define a route with the Route constructor and match a URL using UrlMatcher. Includes error handling for empty requirements.

```APIDOC
## [PHP] Route definition and matching

### Description
Basic route definition and matching using Symfony Routing components.

### Example
```php
use Symfony\Component\Routing\Route;
use Symfony\Component\Routing\RouteCollection;
use Symfony\Component\Routing\Matcher\UrlMatcher;
use Symfony\Component\Routing\RequestContext;

$route = new Route(
    '/blog/{slug}',
    ['_controller' => 'App\Controller\BlogController::show'],
    ['slug' => '[a-z0-9-]+'],
    ['utf8' => true],
    'example.com',
    ['https'],
    ['GET']
);

$routes = new RouteCollection();
$routes->add('blog_show', $route);

$parameters = (new UrlMatcher($routes, new RequestContext(scheme: 'https', host: 'example.com')))
    ->match('/blog/hello-world');
```

### Error Handling
An empty requirement throws an `InvalidArgumentException`.

```php
use Symfony\Component\Routing\Route;

try {
    $route = new Route('/x/{id}', requirements: ['id' => '^$']);
} catch (\InvalidArgumentException $e) {
    // 'Routing requirement for "id" cannot be empty.'
}
```
```

--------------------------------

### get()

Source: https://github.com/symfony/routing

Resolves a route by name, following alias chains. Returns null if the name does not exist.

```APIDOC
## get()

### Description
Resolves a route by name, following alias chains. Returns null if the name does not exist.

### Method
`get`

### Signature
```php
public function get(string $name): ?Route
```

### Parameters
- **$name** (string) - Required - The name of the route to retrieve.

### Returns
- **?Route** - The Route instance or null if not found.

### Throws
- **RouteCircularReferenceException** - When an alias chain loops back on itself.
```

--------------------------------

### runWith() method signature

Source: https://github.com/symfony/routing

Declares the public method that temporarily applies values to the context instance, runs the callback, and restores previous values in a finally block. Null arguments keep current values; the shared instance affects all services using the same context during the callback.

```php
public function runWith(
    callable $callback,
    ?string $baseUrl = null,
    ?string $method = null,
    ?string $host = null,
    ?string $scheme = null,
    ?int $httpPort = null,
    ?int $httpsPort = null,
    ?string $pathInfo = null,
    ?string $queryString = null,
    ?array $parameters = null
): mixed
```

--------------------------------

### runWith()

Source: https://github.com/symfony/routing

Temporarily applies given values to the context instance, runs a callback, and restores previous values afterwards, even if the callback throws.

```APIDOC
## runWith()

### Description
Temporarily applies the given values to this very context instance, runs `$callback`, and restores the previous values afterwards — including when the callback throws (restoration happens in a `finally` block). Arguments left `null` keep their current value. Because the values are applied to the shared instance, every service using the same context generates and matches URLs accordingly during the callback.

### Method
`runWith`

### Signature
```php
public function runWith(
    callable $callback,
    ?string $baseUrl = null,
    ?string $method = null,
    ?string $host = null,
    ?string $scheme = null,
    ?int $httpPort = null,
    ?int $httpsPort = null,
    ?string $pathInfo = null,
    ?string $queryString = null,
    ?array $parameters = null
): mixed
```

### Parameters
- **$callback** (callable) - Required - The callback to execute.
- **$baseUrl** (?string) - Optional - Base URL to apply temporarily.
- **$method** (?string) - Optional - HTTP method to apply temporarily.
- **$host** (?string) - Optional - Host to apply temporarily.
- **$scheme** (?string) - Optional - Scheme to apply temporarily.
- **$httpPort** (?int) - Optional - HTTP port to apply temporarily.
- **$httpsPort** (?int) - Optional - HTTPS port to apply temporarily.
- **$pathInfo** (?string) - Optional - Path info to apply temporarily.
- **$queryString** (?string) - Optional - Query string to apply temporarily.
- **$parameters** (?array) - Optional - Parameters to apply temporarily.

### Return Value
- Returns the return value of the callback.

### Request Example
```php
use Symfony\Component\Routing\RequestContext;
use Symfony\Component\Routing\Generator\UrlGenerator;

$context = new RequestContext();
$generator = new UrlGenerator($routes, $context);

$url = $context->runWith(
    fn () => $generator->generate('blog_show', ['slug' => 'x']),
    scheme: 'https',
    host: 'symfony.com',
);

// context is back to its original state afterwards
```
```

--------------------------------

### UrlGenerator::getRelativePath() (static)

Source: https://github.com/symfony/routing

Returns the target path as a relative reference from the base path. Both paths must be absolute paths (no scheme/host) starting with '/'.

```APIDOC
## [STATIC] getRelativePath()

### Description
Returns the target path as a relative reference from the base path. Both paths must be absolute paths (no scheme/host) starting with `/`.

### Method
STATIC

### Signature
```php
public static function getRelativePath(string $basePath, string $targetPath): string
```

### Parameters
- `$basePath` (string) - Required - The base path.
- `$targetPath` (string) - Required - The target path.

### Return Value
- (string) - The relative path from base to target.

### Examples
- base `/a/b/c/d` → target `/a/b/c/d` gives `''`
- base `/a/b/c/d` → target `/a/b/c/` gives `'./'`
- base `/a/b/c/d` → target `/a/b/` gives `'../'`
- base `/a/b/c/d` → target `/a/b/c/other` gives `'other'`
- base `/a/b/c/d` → target `/a/x/y` gives `'../../x/y'`
```

--------------------------------

### options()

Source: https://github.com/symfony/routing

Sets the options for the route. This method adds the provided options to the route's existing options.

```APIDOC
## options()

### Description
Sets the options for the route. This method adds the provided options to the route's existing options.

### Method
`options(array $options): static`

### Parameters
- `$options` (array) - Required - The options to add.

### Returns
`static` - The current instance for method chaining.
```

--------------------------------

### match()

Source: https://github.com/symfony/routing

Matches a pathinfo string against the route collection and returns the route parameters, including at minimum '_route' => 'route_name' plus defaults, path variables, and host variables. Throws exceptions when no route matches or the method is not allowed.

```APIDOC
## match()

### Description
Matches a pathinfo string against the route collection and returns the route parameters, including at minimum `['_route' => 'route_name']` plus defaults, path variables, and host variables. The matched `_route` name honors `_canonical_route` defaults (see `getAttributes()`, `Matcher/UrlMatcher.php:206`).

### Method
`public function match(string $pathinfo): array`

### Parameters
#### Path Parameters
- `$pathinfo` (string) - Required - The path info to parse (raw format, i.e. not urldecoded)

### Response
#### Success Response (200)
Returns the route parameters, including at minimum `['_route' => 'route_name']` plus defaults, path variables, and host variables.

### Request Example
```php
use Symfony\Component\Routing\Matcher\UrlMatcher;
use Symfony\Component\Routing\RequestContext;
use Symfony\Component\Routing\Route;
use Symfony\Component\Routing\RouteCollection;

$routes = new RouteCollection();
$routes->add('blog_show', new Route(
    '/blog/{slug}',
    ['_controller' => 'App\Blog::show'],
    methods: ['GET']
));

$matcher = new UrlMatcher($routes, new RequestContext(method: 'GET'));
$params = $matcher->match('/blog/lorem-ipsum');
// ['_controller' => 'App\Blog::show', 'slug' => 'lorem-ipsum', '_route' => 'blog_show']
```

### Error Handling
```php
use Symfony\Component\Routing\Exception\MethodNotAllowedException;
use Symfony\Component\Routing\Exception\ResourceNotFoundException;
use Symfony\Component\Routing\Matcher\UrlMatcher;

try {
    $matcher->match('/blog/foo');  // context method POST
} catch (MethodNotAllowedException $e) {
    $allowed = $e->getAllowedMethods(); // ['GET']
} catch (ResourceNotFoundException $e) {
    // no route matched at all
}
```

### Throws
- `NoConfigurationException` - Path is `/`, nothing matched, and no allowed methods/schemes were collected (i.e. no routes configured)
- `MethodNotAllowedException` - Routes matched but none allows the request method; message: `No routes found for "%s".`; carries the allowed methods
- `ResourceNotFoundException` - No route matched and no method/scheme hints were collected
```

--------------------------------

### Configure and use Symfony Router with YAML routes

Source: https://github.com/symfony/routing

Sets up a Router with a DelegatingLoader and YamlFileLoader, then matches and generates URLs. The match() call returns route parameters including '_controller', 'slug', and '_route'; generate() produces the URL '/blog/hello'.

```php
use Symfony\Component\Config\Loader\LoaderResolver;
use Symfony\Component\Routing\Loader\YamlFileLoader;
use Symfony\Component\Routing\Loader\DelegatingLoader;
use Symfony\Component\Config\FileLocator;
use Symfony\Component\Routing\Router;

$locator = new FileLocator([__DIR__.'/config']);
$loader = new DelegatingLoader(new LoaderResolver([
    new YamlFileLoader($locator),
]));

$router = new Router($loader, 'routes.yaml', [
    'cache_dir' => __DIR__.'/var/cache',
    'debug' => false,
]);

$params = $router->match('/blog/hello');      // ['_controller' => ..., 'slug' => 'hello', '_route' => 'blog_show']
$url    = $router->generate('blog_show', ['slug' => 'hello']); // '/blog/hello'
```

--------------------------------

### Using CompiledUrlMatcher with CompiledUrlMatcherDumper

Source: https://github.com/symfony/routing

Shows how to create a CompiledUrlMatcher from compiled routes and match a URL. The match() method returns parameters or throws MethodNotAllowedException, ResourceNotFoundException, or NoConfigurationException.

```php
use Symfony\Component\Routing\Matcher\CompiledUrlMatcher;
use Symfony\Component\Routing\Matcher\Dumper\CompiledUrlMatcherDumper;

$dumper = new CompiledUrlMatcherDumper($routes);
$compiledRoutes = $dumper->getCompiledRoutes();

$matcher = new CompiledUrlMatcher($compiledRoutes, $context);
$params = $matcher->match('/blog/my-post');
```

--------------------------------

### RouterBundle class definition with attributes and methods

Source: https://github.com/symfony/routing

Defines the RouterBundle class with required bundle attributes and public methods for path, build, configure, and loadExtension. The build method adds compiler passes and attribute autoconfiguration, while configure defines the bundle configuration tree.

```php
#[RequiredBundle(ServicesBundle::class)]
#[RequiredBundle(ConsoleBundle::class, ignoreOnInvalid: true)]
class RouterBundle extends AbstractBundle
{
    public function getPath(): string                                   // line 35
    public function build(ContainerBuilder $container): void            // line 40
    public function configure(DefinitionConfigurator $definition): void // line 52
    public function loadExtension(array $config, ContainerConfigurator $configurator, ContainerBuilder $container): void  // line 102
}
```

--------------------------------

### Error handling with MethodNotAllowedException and ResourceNotFoundException

Source: https://github.com/symfony/routing

Shows how to catch exceptions thrown by match() when the method is not allowed or no route matches. The allowed methods are retrieved from the exception.

```php
use Symfony\Component\Routing\Exception\MethodNotAllowedException;
use Symfony\Component\Routing\Exception\ResourceNotFoundException;
use Symfony\Component\Routing\Matcher\UrlMatcher;

try {
    $matcher->match('/blog/foo');  // context method POST
} catch (MethodNotAllowedException $e) {
    $allowed = $e->getAllowedMethods(); // ['GET']
} catch (ResourceNotFoundException $e) {
    // no route matched at all
}
```

--------------------------------

### Route::__construct

Source: https://github.com/symfony/routing

Creates a new Route instance with the given path pattern and optional configuration. The constructor delegates to the fluent setters for each parameter.

```APIDOC
## Route::__construct

### Description
Creates a new Route instance with the given path pattern and optional configuration. The constructor delegates to the fluent setters for each parameter.

### Method
Constructor

### Signature
```php
public function __construct(
    string $path,
    array $defaults = [],
    array $requirements = [],
    array $options = [],
    ?string $host = '',
    string|array $schemes = [],
    string|array $methods = [],
    ?string $condition = ''
)
```

### Parameters
- **$path** (string) - Required - The path pattern to match, e.g. `/blog/{slug}`
- **$defaults** (array) - Optional - Default parameter values
- **$requirements** (array<string,\Stringable>) - Optional - Parameter requirements (regexes)
- **$options** (array) - Optional - Route options (see `setOptions()`)
- **$host** (?string) - Optional - Host pattern to match
- **$schemes** (string|string[]) - Optional - Required URI scheme or array of restricted schemes
- **$methods** (string|string[]) - Optional - Required HTTP method or array of restricted methods
- **$condition** (?string) - Optional - An expression that must evaluate to true for the route to match

### Return Value
Returns a new `Route` instance.
```

--------------------------------

### Instantiate and warm up DependencyInjection Router

Source: https://github.com/symfony/routing

Creates a Router instance with a container and YAML resource, then warms caches for deployment. The warmUp() method forces matcher/generator cache generation and returns class names to warm.

```php
use Symfony\Component\Routing\DependencyInjection\Router;

$router = new Router($container, 'config/routes.yaml', [
    'cache_dir' => '/var/cache/app',
    'debug' => true,
]);

// warm the caches for deployment
$router->warmUp('/var/cache/app');
```

--------------------------------

### Router::__construct

Source: https://github.com/symfony/routing

Creates a new Router instance. The constructor accepts a loader, a resource, and optional configuration options, context, logger, and default locale.

```APIDOC
## Router::__construct

### Description
Creates a new Router instance. The constructor accepts a loader, a resource, and optional configuration options, context, logger, and default locale.

### Method
Constructor

### Signature
```php
public function __construct(
    protected LoaderInterface $loader,
    protected mixed $resource,
    array $options = [],
    ?RequestContext $context = null,
    protected ?LoggerInterface $logger = null,
    protected ?string $defaultLocale = null,
)
```

### Parameters
- `$loader` (LoaderInterface) - Required - Loader used to obtain the `RouteCollection` from `$resource`
- `$resource` (mixed) - Required - Main resource to load (e.g. a file path, service id, closure)
- `$options` (array) - Optional - Router options, see [configuration.md](../configuration.md)
- `$context` (?RequestContext) - Optional - Request context used for matching and generating
- `$logger` (?LoggerInterface) - Optional - PSR-3 logger (forwarded to the generator)
- `$defaultLocale` (?string) - Optional - Default locale for localized route generation
```

--------------------------------

### Using EnumRequirement in a route

Source: https://github.com/symfony/routing

Shows how to use EnumRequirement with a BackedEnum in a route requirement. The example defines a Status enum and uses EnumRequirement(Status::class) in the Route attribute, equivalent to 'draft|published|archived'.

```php
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Routing\Requirement\EnumRequirement;

enum Status: string
{
    case Draft = 'draft';
    case Published = 'published';
    case Archived = 'archived';
}

class ArticleController
{
    #[Route('/articles/{status}', name: 'article_list', requirements: ['status' => new EnumRequirement(Status::class)])]
    public function list(string $status): Response { /* … */ }

    // equivalent to: requirements: ['status' => 'draft|published|archived']
}
```

--------------------------------

### StaticPrefixCollection class skeleton

Source: https://github.com/symfony/routing

Internal class that builds a prefix tree of routes while preserving route order. It is used by the matcher dumper to group routes sharing common prefixes and to match hosts by common suffix. addRoute() nests or merges items with common ancestors, and populateCollection() linearizes the tree back into a RouteCollection.

```php
/** @internal */
class StaticPrefixCollection
{
    public function __construct(private string $prefix = '/')   // line 41
    public function getPrefix(): string                         // line 46
    public function getRoutes(): array                          // line 54
    public function addRoute(string $prefix, array|self $route): void  // line 58
    public function populateCollection(RouteCollection $routes): RouteCollection  // line 122
    public static function handleError(int $type, string $msg): bool  // line 193
}
```

--------------------------------

### RouterMatchCommand class definition

Source: https://github.com/symfony/routing

Defines the router:match console command. The constructor requires a RouterInterface and accepts an iterable of expression language providers. The command simulates a path info match and prints trace lines.

```php
#[AsCommand(name: 'router:match', description: 'Help debug routes by simulating a path info match')]
/** @final */
class RouterMatchCommand extends Command
{
    public function __construct(
        private RouterInterface $router,
        private iterable $expressionLanguageProviders = [],
    )
}
```

--------------------------------

### Getters / Setters

Source: https://github.com/symfony/routing

Provides getter and setter methods for the context properties: base URL, path info, method, host, scheme, ports, query string, and parameters.

```APIDOC
## Getters / Setters

### Description
Provides getter and setter methods for the context properties: base URL, path info, method, host, scheme, ports, query string, and parameters.

### Methods

#### getBaseUrl()
```php
public function getBaseUrl(): string
```
Returns the base URL.

#### setBaseUrl()
```php
public function setBaseUrl(string $baseUrl): static
```
Sets the base URL (trailing '/' trimmed).

#### getPathInfo()
```php
public function getPathInfo(): string
```
Returns the path info.

#### setPathInfo()
```php
public function setPathInfo(string $pathInfo): static
```
Sets the path info.

#### getMethod()
```php
public function getMethod(): string
```
Returns the HTTP method.

#### setMethod()
```php
public function setMethod(string $method): static
```
Sets the HTTP method (stored strtoupper()).

#### getHost()
```php
public function getHost(): string
```
Returns the host.

#### setHost()
```php
public function setHost(string $host): static
```
Sets the host (stored strtolower()).

#### getScheme()
```php
public function getScheme(): string
```
Returns the scheme.

#### setScheme()
```php
public function setScheme(string $scheme): static
```
Sets the scheme (stored strtolower()).

#### getHttpPort()
```php
public function getHttpPort(): int
```
Returns the HTTP port.

#### setHttpPort()
```php
public function setHttpPort(int $httpPort): static
```
Sets the HTTP port.

#### getHttpsPort()
```php
public function getHttpsPort(): int
```
Returns the HTTPS port.

#### setHttpsPort()
```php
public function setHttpsPort(int $httpsPort): static
```
Sets the HTTPS port.

#### getQueryString()
```php
public function getQueryString(): string
```
Returns the query string.

#### setQueryString()
```php
public function setQueryString(?string $queryString): static
```
Sets the query string (null tolerated, cast to string).

#### getParameters()
```php
public function getParameters(): array
```
Returns all parameters.

#### setParameters()
```php
public function setParameters(array $parameters): static
```
Sets all parameters.

#### getParameter()
```php
public function getParameter(string $name): mixed
```
Returns a single parameter by name.

#### hasParameter()
```php
public function hasParameter(string $name): bool
```
Checks if a parameter exists (array_key_exists).

#### setParameter()
```php
public function setParameter(string $name, mixed $parameter): static
```
Sets a single parameter.

#### isSecure()
```php
public function isSecure(): bool
```
Returns true if the scheme is 'https'.
```

--------------------------------

### RedirectableUrlMatcher abstract class declaration and match method

Source: https://github.com/symfony/routing

Abstract matcher that extends UrlMatcher and implements RedirectableUrlMatcherInterface. The match() method wraps the parent and intercepts ResourceNotFoundException to handle redirects for HEAD and GET requests.

```php
abstract class RedirectableUrlMatcher extends UrlMatcher implements RedirectableUrlMatcherInterface
{
    public function match(string $pathinfo): array
}
```

--------------------------------

### Catch MissingMandatoryParametersException and get missing parameters

Source: https://github.com/symfony/routing

Use this snippet to handle a generation failure when a required route parameter (e.g., {slug}) has no default. The exception provides getRouteName() and getMissingParameters() to identify the route and missing variables.

```php
use Symfony\Component\Routing\Exception\MissingMandatoryParametersException;

try {
    $generator->generate('blog_show'); // {slug} has no default
} catch (MissingMandatoryParametersException $e) {
    $e->getRouteName();        // 'blog_show'
    $e->getMissingParameters(); // ['slug']
}
```

--------------------------------

### Using CompiledUrlGenerator with dumper

Source: https://github.com/symfony/routing

Shows how to instantiate CompiledUrlGenerator with compiled routes from CompiledUrlGeneratorDumper. The generate() method resolves locale-suffixed route names, throws RouteNotFoundException for unknown names, triggers deprecations, and delegates to doGenerate().

```php
use Symfony\Component\Routing\Generator\CompiledUrlGenerator;
use Symfony\Component\Routing\Generator\Dumper\CompiledUrlGeneratorDumper;
use Symfony\Component\Routing\RequestContext;

$dumper = new CompiledUrlGeneratorDumper($routes);
$compiled = array_merge($dumper->getCompiledRoutes(), $dumper->getCompiledAliases());

$generator = new CompiledUrlGenerator($compiled, new RequestContext());
$url = $generator->generate('blog_show', ['slug' => 'x']);
```

--------------------------------

### Custom RedirectableUrlMatcher implementation with redirect method

Source: https://github.com/symfony/routing

Example subclass that implements the required redirect() method, returning an array with controller, path, permanent flag, scheme, and route. Used to customize redirect behavior for the matcher.

```php
use Symfony\Component\Routing\Matcher\RedirectableUrlMatcher;

class MyRedirectableMatcher extends RedirectableUrlMatcher
{
    public function redirect(string $path, string $route, ?string $scheme = null): array
    {
        return [
            '_controller' => 'App\Controller\RedirectController::urlRedirectAction',
            'path' => $path,
            'permanent' => false,
            'scheme' => $scheme,
            '_route' => $route,
        ];
    }
}
```

--------------------------------

### Constructor

Source: https://github.com/symfony/routing

Creates an empty RouteCollection instance.

```APIDOC
## Constructor

### Description
Creates an empty RouteCollection instance.

### Method
`__construct`

### Signature
```php
public function __construct()
```

### Parameters
None.

### Returns
A new RouteCollection instance.
```

--------------------------------

### format()

Source: https://github.com/symfony/routing

Sets the format for the route. This method adds the '_format' default to the route.

```APIDOC
## format()

### Description
Sets the format for the route. This method adds the '_format' default to the route.

### Method
`format(string $format): static`

### Parameters
- `$format` (string) - Required - The format string.

### Returns
`static` - The current instance for method chaining.
```
Tokens:
Raw