Skip to the stories
AI & ML

Symfony 8.2 Routing: Query Defaults, Stacked Conditions and Scoped URL Context

  • Javier Eguiluz
  • 702 reads

Symfony 8.2 lets routes declare default query parameters, combine import-level route conditions, and temporarily override URL generation context.

Symfony 8.2 Routing: Query Defaults, Stacked Conditions and Scoped URL Context

Symfony 8.2 takes a set of routing pain points that most teams have worked around by hand and turns them into framework features. Routes can now carry default query parameters, import-level conditions no longer clobber route-level ones, and URL generation can run with a temporary context. None of these changes is dramatic on its own. Together, they remove repetition and make route composition behave more predictably, which is what the Routing component needs as applications grow. This follows the firewall-per-route change that came earlier in the 8.2 cycle.

Ousama Ben Younes

Default query parameters on routes

Symfony 7.3 added the special _query parameter for adding query string values when generating URLs. The gap was that routes themselves couldn't declare those values. If a listing page always defaulted to page 1 and sorted by name, every generate() and path() call had to repeat that information, and every controller had to handle the defaults separately. That's the kind of duplication that drifts over time.

In 8.2, a route can define a _query default. Because it's a regular route default, it works wherever routes are configured, whether in attributes, YAML, XML or PHP. A controller can declare #[MapQueryParameter] arguments, and Symfony fills in the defaults when the incoming request leaves those parameters out. The route still matches on path alone, since defaults never affect matching. The query string is only touched during generation and request population.

Two details matter in practice. First, values you pass to generate() override the defaults. Second, passing null through a _query array removes a default entirely, so you can drop sort from a generated URL without defining a second route. That's a small API decision, but it's the one that keeps the feature from becoming a source of surprising URLs. The change came from a contribution by Ousama Ben Younes in #65073.

Nicolas Grekas

Combining conditions on imported routes

This one has bitten people who organize controllers into directories and then want to gate an entire group. Before 8.2, the condition option on an import replaces the condition of every route it brings in. A group-level condition and a route-level #[Route(condition: '...')] could not coexist. You either lost one, or you pushed the group logic into each controller.

The new add_condition option (addCondition() in PHP) changes the semantics. It doesn't replace anything. It combines the expression you supply with each route's existing condition using and. So a YAML import of an Api/ directory with add_condition set to a check on an X-Api-Version header will yield, for a route that already requires a GET or HEAD method, a compound condition that requires both. The generated expression wraps each side in parentheses, which is worth knowing if you ever debug a condition by reading the compiled form.

My read is that this is the more consequential change of the three for large applications. It makes imports composable, which means a platform team can attach a cross-cutting constraint, such as an API version gate, to a directory without touching the controllers inside it. The trade-off is that you now need to be deliberate about where conditions live. Stacking them across several import levels is straightforward, but a reviewer has to keep the full combined expression in mind. This work was contributed by Nicolas Grekas in #66004.

Hubert Lenoir

Generating URLs for another context

Every generated URL inherits the host, scheme and base URL of the current request. That's the right default for a web request, but it breaks down in multi-tenant and multi-domain applications. A common case is a background job or a notification that builds a link to a tenant's own domain, such as an invoice link in an email. Until now, the usual approach was to mutate the shared RequestContext, generate the URL, and then restore each value by hand. Forgetting one restore, or skipping it when an exception fires, leaks the wrong context into later work in the same process.

Symfony 8.2 adds RequestContext::runWith(). You pass it a callback and the values to apply, and it restores the original context afterward, including when the callback throws. The example in the release notes passes a tenant's domain as host and forces https as scheme, and the generated URL comes back as an absolute link on that domain. You can also override baseUrl, method, the HTTP and HTTPS ports, pathInfo, queryString and parameters. Anything you leave out keeps its current value.

The important detail is scope. The values change the context object itself, not just the one generator call. That means the router, the UrlHelper, and the Twig url() and path() functions all see the temporary values while the callback runs. That's exactly what you want for a block of rendering that should behave as if it were on the tenant's domain, but it also means you should keep the callback small. Anything nested inside it inherits the override.

What to watch

The three features share a theme: they let route configuration express intent once, rather than scattering it across controllers and call sites. The open questions are about adoption and edge cases. Teams with heavy use of _query may need to audit whether existing controllers already compensate for defaults in ways that now double up. Teams that stacked conditions by copying them into individual routes will want to confirm the combined expressions still say what they mean. And anyone using runWith() in long-running workers should test that nothing outside the callback picks up stale state.

If you maintain a multi-domain application or a large attribute-routed codebase, 8.2 is worth reading closely in the routing docs before you upgrade. The features are small in code but they change where you put logic, and that's usually where the maintenance cost lives.

Source: Javier Eguiluz · symfony.com

From the same set