Basic Route Configuration¶

Defining a route is easy, and a typical application will have lots of routes. A basic route consists of just two parts: the path to match and a defaults array:

This route matches the homepage (/) and maps it to the AppBundle:Main:homepage controller. The _controller string is translated by Symfony into an actual PHP function and executed. That process will be explained shortly in the Controller Naming Pattern section.

Routing with Placeholders¶

Of course the routing system supports much more interesting routes. Many routes will contain one or more named "wildcard" placeholders:

The path will match anything that looks like /blog/*. Even better, the value matching the {slug} placeholder will be available inside your controller. In other words, if the URL is /blog/hello-world, a $slug variable, with a value of hello-world, will be available in the controller. This can be used, for example, to load the blog post matching that string.

The path will not, however, match simply /blog. That's because, by default, all placeholders are required. This can be changed by adding a placeholder value to the defaults array.

Required and Optional Placeholders¶

To make things more exciting, add a new route that displays a list of all the available blog posts for this imaginary blog application:

So far, this route is as simple as possible - it contains no placeholders and will only match the exact URL /blog. But what if you need this route to support pagination, where /blog/2 displays the second page of blog entries? Update the route to have a new {page} placeholder:

Like the {slug} placeholder before, the value matching {page} will be available inside your controller. Its value can be used to determine which set of blog posts to display for the given page.

But hold on! Since placeholders are required by default, this route will no longer match on simply /blog. Instead, to see page 1 of the blog, you'd need to use the URL /blog/1! Since that's no way for a rich web app to behave, modify the route to make the {page} parameter optional. This is done by including it in the defaults collection:

By adding page to the defaults key, the {page} placeholder is no longer required. The URL /blog will match this route and the value of the page parameter will be set to 1. The URL /blog/2 will also match, giving the page parameter a value of 2. Perfect.

Adding Requirements¶

Take a quick look at the routes that have been created so far:

Can you spot the problem? Notice that both routes have patterns that match URLs that look like /blog/*. The Symfony router will always choose the first matching route it finds. In other words, the blog_show route will never be matched. Instead, a URL like /blog/my-blog-post will match the first route (blog) and return a nonsense value of my-blog-post to the {page} parameter.

The answer to the problem is to add route requirements. The routes in this example would work perfectly if the /blog/{page} path only matched URLs where the {page} portion is an integer. Fortunately, regular expression requirements can easily be added for each parameter. For example:

The \d+ requirement is a regular expression that says that the value of the {page} parameter must be a digit (i.e. a number). The blog route will still match on a URL like /blog/2 (because 2 is a number), but it will no longer match a URL like /blog/my-blog-post (because my-blog-post is not a number).

As a result, a URL like /blog/my-blog-post will now properly match the blog_show route.

Since the parameter requirements are regular expressions, the complexity and flexibility of each requirement is entirely up to you. Suppose the homepage of your application is available in two different languages, based on the URL:

For incoming requests, the {_locale} portion of the URL is matched against the regular expression (en|fr).

Adding HTTP Method Requirements¶

In addition to the URL, you can also match on the method of the incoming request (i.e. GET, HEAD, POST, PUT, DELETE). Suppose you create an API for your blog and you have 2 routes: One for displaying a post (on a GET or HEAD request) and one for updating a post (on a PUT request). This can be accomplished with the following route configuration:

Despite the fact that these two routes have identical paths (/api/posts/{id}), the first route will match only GET or HEAD requests and the second route will match only PUT requests. This means that you can display and edit the post with the same URL, while using distinct controllers for the two actions.

Adding a Host Requirement¶

You can also match on the HTTP host of the incoming request. For more information, see How to Match a Route Based on the Host in the Routing component documentation.

Advanced Routing Example¶

At this point, you have everything you need to create a powerful routing structure in Symfony. The following is an example of just how flexible the routing system can be:

As you've seen, this route will only match if the {_locale} portion of the URL is either en or fr and if the {year} is a number. This route also shows how you can use a dot between placeholders instead of a slash. URLs matching this route might look like:

• /articles/en/2010/my-post
• /articles/fr/2010/my-post.rss
• /articles/en/2013/my-latest-post.html

Special Routing Parameters¶

As you've seen, each routing parameter or default value is eventually available as an argument in the controller method. Additionally, there are three parameters that are special: each adds a unique piece of functionality inside your application:

_controller

As you've seen, this parameter is used to determine which controller is executed when the route is matched.

_format

Used to set the request format (read more).

_locale

Used to set the locale on the request (read more).

Prefixing Imported Routes¶

You can also choose to provide a "prefix" for the imported routes. For example, suppose you want to prefix all routes in the AppBundle with /site (e.g. /site/blog/{slug} instead of /blog/{slug}):

The path of each route being loaded from the new routing resource will now be prefixed with the string /site.

Adding a Host Requirement to Imported Routes¶

You can set the host regex on imported routes. For more information, see Using Host Matching of Imported Routes.

Generating URLs with Query Strings¶

The generate method takes an array of wildcard values to generate the URI. But if you pass extra ones, they will be added to the URI as a query string:

1
2
3
4
5

$this->get('router')->generate('blog', array(
    'page' => 2,
    'category' => 'Symfony'
));
// /blog/2?category=Symfony

Generating URLs from a Template¶

The most common place to generate a URL is from within a template when linking between pages in your application. This is done just as before, but using a template helper function:

Generating Absolute URLs¶

By default, the router will generate relative URLs (e.g. /blog). From a controller, simply pass UrlGeneratorInterface::ABSOLUTE_URL to the third argument of the generateUrl() method:

use Symfony\Component\Routing\Generator\UrlGeneratorInterface;

$this->generateUrl('blog_show', array('slug' => 'my-blog-post'), UrlGeneratorInterface::ABSOLUTE_URL);
// http://www.example.com/blog/my-blog-post

From a template, in Twig, simply use the url() function (which generates an absolute URL) rather than the path() function (which generates a relative URL). In PHP, pass true to generate():