Routing

Introduction#

A route is like mapping a URL to an action (function) in a Controller class. The following topic will focus on creating routes, passing parameters to the Controller class via a route either using YAML or annotation.

Remarks#

It’s useful to see what is generated by Symfony framework, this one provide tools to watch all routes of an specific application.

From the Symfony Doc, use (in a shell) :

php bin/console debug:router

As well, you can watch all the relevant routes informations in the Framework profiler, in the routing menu :

Routing using YAML

The routing configuration is included in your app/config/config.yml file, by default the app/config/routing.yml file.

From there you can link to your own routing configuration in a bundle

# app/config/routing.yml

app:
    resource: "@AppBundle/Resources/config/routing.yml"

It might also contain several application global routes.

In your own bundle you can configure, routes which serve two purposes:

• Matching against a request, such that the correct action is called for the request.
• Generating an URL from the name and route parameters.

Below is an example YAML route configuration:

# src/AppBundle/Resources/config/routing.yml

my_page:
    path: /application/content/page/{parameter}
    defaults:
        _controller: AppBundle:Default:myPage
        parameter: 42
    requirements:
        parameter: '\d+'
    methods: [ GET, PUT ]
    condition: "request.headers.get('User-Agent') matches '/firefox/i'"

The route is named my_page, and calls the myPageAction of the DefaultController in the AppBundle when requested. It has a parameter, named parameter with a default value. The value is only valid when it matches the regex \d+. For this route, only the HTTP methods GET and PUT are accepted. The condition is an expression in the example the route won’t match unless the User-Agent header matches firefox. You can do any complex logic you need in the expression by leveraging two variables that are passed into the expression: context (RequestContext) and request (Symfony Request).

A generated route with the parameter value of 10 might look like /application/content/page/10.

Routing using annotations

The routing configuration is included in your app/config/config.yml file, by default the app/config/routing.yml file.

From there you can link to the controllers that have annotated routing configuration:

# app/config/routing.yml

app:
    resource: "@AppBundle/Controller"
    type:     annotation

In your own bundle you can configure, routes which serve two purposes:

• Matching against a request, such that the correct action is called for the request.
• Generating an URL from the name and route parameters.

Below is an example annotated route configuration:

// src/AppBundle/Controller/DefaultController.php

use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Method;

/**
 * @Route("/application")
 */
class DefaultController extends Controller {
    /**
     * @Route("/content/page/{parameter}",
     *        name="my_page",
     *        requirements={"parameter" = "\d+"},
     *        defaults={"parameter" = 42})
     * @Method({"GET", "PUT"})
     */
    public function myPageAction($parameter)
    {
        // ...
    }
}

The controller is annotated with a prefix route, such that any configured route in this controller will be prepended using the prefix.

The configured route is named my_page, and calls the myPageAction function when requested. It has a parameter, named parameter with a default value. The value is only valid when it matches the regex \d+. For this route, only the HTTP methods GET and PUT are accepted.

Notice that the parameter is injected into the action as a function parameter.

A generated route with the parameter value of 10 might look like /application/content/page/10.

Powerful Rest Routes

Traditionally, you can use routing to map an the request with the Routing Component who handled request and response parameters by HttpFoundation Component.

Additionally, a custom route parameter can be created by using the FOSRestBundle to extends the default functionalities of the Routing Component.

This is useful for creating REST routes, an really useful to specify how to tranfer structured data like XML or json file in a request (and a response).

See FOSRestBundle Doc for more information, and especially this annotation :

use FOS\RestBundle\Controller\Annotations\FileParam;

/**
 * @FileParam(
 *   name="",
 *   key=null,
 *   requirements={},
 *   default=null,
 *   description="",
 *   strict=true,
 *   nullable=false,
 *   image=false
 * )
 */