In this article we assume that you are familiar with The YAML Format and Configuration File Principles.

The routing.yml configuration file allows the definition of routes. The main routing.yml file for an application can be found in the apps/APP_NAME/config/ directory. It contains a list of named route definitions:

ROUTE_1:
  # definition of route 1

ROUTE_2:
  # definition of route 2

# ...

When a request comes in, the routing system tries to match a route to the incoming URL. The first route that matches wins, so the order in which routes are defined in the routing.yml configuration file is important.

When the routing.yml configuration file is read, each route is converted to an object of class class:

ROUTE_NAME:
  class: CLASS_NAME
  # configuration if the route

The class name should extend the sfRoute base class. If not provided, the sfRoute base class is used as a fallback.

# Main routing configuration
route_name:
  class:                    class_name
  url:                      url_string
  type:                     route_type
  param:
    module:                   module_name
    action:                   action_name
    sf_format:                <html | atom | xml | json | yaml | other_formats>
    sf_culture:               culture_name
    variable_name:            value
  params:                   array_of_parameters
  options:
    variable_prefixes:        [prefix1, prefix2, ...]
    segment_separators:       [seperator1, seperator2, ...]
    suffix:                   suffix_string
    generate_shortest_url:    <true | false>
    extra_parameters_as_query_string:<true | false>
    variable_regex:           regular_expression
  requirements:
    sf_format:                format_requirements
    sf_culture:               culture_requirements
    variable_name:            regular_expression

# sfRequestRoute configuration options
route_name:
  class:                    sfRequestRoute
  requirements:
    sf_method:                [<get | post | header | put | delete>, ...]

# sfObjectRoute configuration options
route_name:
  class:                    <sfObjectRoute | sfDoctrineRoute | sfPropelRoute>
  options:
    model:                    model_name
    type:                     <object | list>
    method:                   model_method
    allow_empty:              <true | false>
    convert:                  method_name
    method_for_query:         method_name
    method_for_criteria:      method_name

# sfObjectRouteCollection configuration options
route_name:
  class:                    <sfObjectRouteCollection | sfDoctrineRouteCollection | sfPropelRouteCollection>
  options:
    model:                    model_name
    actions:                  [<list | new | create | edit | update | delete | show>, ...]
    module:                   module_name
    prefix_path:              prefix_path_string
    column:                   column_name
    with_show:                <true | false>
    segment_names:            { edit: edit_name, new: new_name }
    with_wildcard_routes:     <true | false>
    route_class:              class_name
    collection_actions:       { action1: [<get | post | header | put | delete>,...], action2: post, ... }
    object_actions:           { action1: [<get | post | header | put | delete>,...], action2: put, ... }
    requirements:
      variable_name:            regular_expression
    model_methods:
      list:                     method_name
      object:                   method_name

Main routing configuration

route_name

Defines unique route name, which is there for legibility and speed, and can be used by the link helpers (eg.: link_to, url_for).

route_name > class

Defines the route class to use for the route. All route classes extends the sfRoute base class, which provides the required settings to configure a route.
Default:
sfRoute (or sfRouteCollection if type is collection, see below)

route_name > url

Defines the pattern that must match an incoming URL for the route to be used for the current request.
The pattern is made of segments:
  • variables (a word prefixed with a colon :). The module and action variable are special as they are used by symfony to determine the action to execute
  • constants
  • a wildcard (*) to match a sequence of variable/value pairs separated by slashes (/)
Each segment must be separated by one of the pre-defined separator (/ or . by default).
Default:
/

route_name > type

Defines route type. If set to collection, the route will be read as a route collection.
This setting is automatically set to collection by the config handler class if the class name contains the word Collection. It means that most of the time, you do not need to use this setting.

Request parameters

route_name > param

Defines an array of request parameters associated with the route. They can be default values for variables contained in the url, or any other variable relevant for this route.

route_name > param > module

This is a special variable which is used by symfony in pair with the action varaible to determine the module and action to execute. You can also use module in your url pattern:
default_index:
  url:   /:module
  param: { action: index }
The module value can then be retrieved in the action class with $request->getParameter('module').
See definition of the action variable as well.

route_name > param > action

This is a special variable which is used by symfony in pair with the module varaible to determine the module and action to execute. You can also use action variable in your url pattern:
default:
  url:   /:module/:action/*
The action value can then be retrieved in the action class with $request->getParameter('action').
See definition of the module variable as well.

route_name > param > sf_format

This is a special variable which is used by symfony to determine the requested format.
The symfony framework has native support for formats and mime-types. This means that the same Model and Controller can have different templates based on the requested format. The default format is HTML but symfony supports several other formats out of the box like txt, js, css, json, xml, rdf, or atom. By default, symfony will change the response Content-Type according to the format, and for all non-HTML formats, the layout is disabled.
The sf_format value can be retrieved in the action with $request->getRequestFormat().
Default:
html

route_name > param > sf_culture

This is a special variable which is used by symfony to determine the user culture.
By default, the user culture is the one configured in the settings.yml configuration file default_culture option. In an action you can manage the user culture by calling the setCulture() and getCulture() methods on the User object:
$this->getUser()->setCulture('fr_BE');
echo $this->getUser()->getCulture();
The culture can be embedded in the url:
job_search:
  url:   /:sf_culture/search
  param: { module: job, action: search }
When the sf_culture variable is used in a route, symfony will automatically use its value to change the culture of the user.

route_name > param > variable_name

In the param section, you can define any variable relevant for this route. The parameters don't need to be variables found in the url pattern. In the example below, the display parameter takes the value true, even if it is not present in the URL.
article_by_id:
  url:          /article/:id
  param:        { module: article, action: read, id: 1, display: true }
The display value can then be retrieved in an action with $request->getParameter('display').

route_name > params

This setting is equivalent to the param settings.
Default:
An empty array

Routing options

route_name > options

Defines an array of options to be passed to the route object to further customize its behavior. The following sections describe the available options for each route class.

route_name > options > variable_prefixes

Defines the list of characters that starts a variable name in a route pattern.
Default:
[:]

route_name > options > segment_separators

Defines the list of route segment separators.
Default:
[/, .]

route_name > options > suffix

Defines the suffix to use for this route. This suffix is added to the end of the url. This option is deprecated and is not useful anymore.
Default:
Empty string

route_name > options > generate_shortest_url

Specifies whether to generate the shortest URL possible. If set to true, this option will tell the routing system to generate the shortest route possible by omitting empty route variables in the end of the URL. For example if you have this URL pattern:
/users/:username/:sort/:start/
the :username is set to 'test1' and the other two variables (:sort and :start) are left unset, but have default values defined, then the routing system will generate this URL:
/users/test1/
Set generate_shortest_url to false if you want your routes to be backward compatible with symfony 1.0 and 1.1.
Possible values:
<true | false>
Default:
true

route_name > options > extra_parameters_as_query_string

When some parameters are not used in the generation of a route, this option allows those extra parameters to be converted to a query string. Set it to false to fallback to the behavior of symfony 1.0 or 1.1. In those versions, the extra parameters were just ignored by the routing system.
Possible values:
<true | false>
Default:
true

route_name > options > variable_regex

Defines regular expression used to adjust the characters allowed in your variable names.
Default:
[\w\d_]+

Routing requirements

route_name > requirements

Defines an array of requirements that must be satisfied by the url variables. The keys are the url variables and the values are regular expressions that the variable values must match.
The regular expression will be included in another regular expression, and as such, you don't need to wrap them between separators, nor do you need to bound them with ^ or $ to match the whole value.

route_name > requirements > sf_format

Restricts requested formats. You can restrict sf_format to one format as well as to several formats. For example if you want to restrict formats to html and atom do the folowing:
requirements:
  sf_format: (?:html|atom)

route_name > requirements > sf_culture

Restricts user cultures. You can restrict sf_culture to one user culture as well as to several user cultures. For example if you want to restrict user cultures to fr and en do the folowing:
requirements:
  sf_culture: (?:fr|en)

route_name > requirements > variable_name

Each url pattern variable can be validated by a regular expression defined using the requirements entry of a route definition, The keys are the url variables and the values are regular expressions that the variable values must match:
job:
  url:   /job/:company/:location/:id/:position
  param: { module: job, action: show }
  requirements:
    id: \d+
The above requirements entry forces the id to be a numeric value. If not, the route won't match and the routing system will keep on looking for a match in the following rules.

sfRequestRoute configuration options

route_name > class

sfRequestRoute represents a route that is request aware. It extends the sfRoute class and hence it inherits all configuration options that sfRoute has. In addition sfRequestRoute class exposes a sf_method requirement, allowing you to create RESTful interfaces based on HTTP request method. Requiring a route to only match for some HTTP methods is not totally equivalent to using sfWebRequest::isMethod() in your actions. That's because the routing will continue to look for a matching route if the method does not match the expected one.
Possible values:
sfRequestRoute

route_name > requirements > sf_method

This option is to be used in the requirements array. It enforces the HTTP request in the route matching process and restricts a route to only match for certain request methods, eg.:
content:
  class: sfRequestRoute
  url:   /content
  param:
    module: content
    action: index
  requirements:
    sf_method: [get]
Possible values:
[<get | post | header | put | delete>, ...]
Default:
get

sfObjectRoute configuration options

route_name > class

sfObjectRoute class is optimized for routes that represent database objects or collections of database objects.
sfDoctrineRoute class extends sfObjectRoute and is optimized for routes that represent Doctrine objects or collections of Doctrine objects.
sfPropelRoute class extends sfObjectRoute and is optimized for routes that represent Propel objects or collections of Propel objects.
Every class extends the sfRequestRoute class and hence they inherit all configuration options that sfRequestRoute and sfRoute has.
The route is also able to find the object related to a given URL. The related object can be retrieved with the getObject() method of the route object:
class jobActions extends sfActions
{
  public function executeShow(sfWebRequest $request)
  {
    $this->job = $this->getRoute()->getObject();
    $this->forward404Unless($this->job);
  }
}
The related object of a route is lazy loaded. It is only retrieved from the database if you call the getRoute() method.
Possible values:
<sfObjectRoute | sfDoctrineRoute | sfPropelRoute>

route_name > options > model

Defines the name of the model class to be associated with the current route. This option is mandatory.

route_name > options > type

Defines the type of route you want for your model; it can be either object or list. A route of type object represents a single model object, and a route of type list represents a collection of model objects. This option is mandatory.
Possible values:
<object | list>

route_name > options > method

Defines the method to call on the model class to retrieve the object(s) associated with this route. This must be a static method. The method is called with the parameters of the parsed route as an argument. This option is mandatory.

route_name > options > allow_empty

If the this option is set to false, the route will throw a 404 exception if no object is returned by the call to the model method.
Possible values:
<true | false>
Default:
true

route_name > options > convert

Defines a method to call to convert a model object to an array of parameters suitable for generating a route based on this model object. It must returns an array with at least the required parameters of the route pattern (as defined by the url setting).
Default:
toParams

route_name > options > method_for_query

Defines the method to call on the model to retrieve the object(s) associated with the current request. The current query object is passed as an argument.
If the option is not set, the query is just "executed" with the execute() method.
This option is available only for sfDoctrineRoute class.

route_name > options > method_for_criteria

Defines the method called on the model Peer class to retrieve the object(s) associated with the current request. The method is called with the parameters of the parsed route as an argument.
This option is available only for sfPropelRoute class.
Default:
doSelect (for collections), doSelectOne (for single objects)

sfObjectRouteCollection configuration options

route_name > class

The sfObjectRouteCollection represents a collection of routes bound to objects.
The sfDoctrineRouteCollection route class extends the sfObjectRouteCollection, and changes the default route class to sfDoctrineRoute (see the route_class option below).
The sfPropelRouteCollection route class extends the sfObjectRouteCollection, and changes the default route class to sfPropelRoute.
Route collection can be used to define the classic seven actions possible for a model (index, new, edit, create, update, delete and show);
Possible values:
<sfObjectRouteCollection | sfDoctrineRouteCollection | sfPropelRouteCollection>

route_name > options > model

Defines the name of the model class to be associated with the current route. This option is mandatory.

route_name > options > actions

Defines an array of authorized actions for the route. The actions must be a sub-set of all available actions: list, new, create, edit, update, delete, and show. Eg.:
article:
  class:   sfObjectRouteCollection
  options:
    model:          Article
    actions:        [new, create]
If the option is set to false, the default, all actions will be available except for the show one if the with_show option is set to false (see below).
Default:
false

route_name > options > module

Defines the module name.
Default:
The route name

route_name > options > prefix_path

Defines a prefix to prepend to all url patterns. It can be any valid pattern and can contain variables and several segments.
Default:
/ followed by the route name

route_name > options > column

Defines the column of the model to use as the unique identifier for the model object.
Default:
id

route_name > options > with_show

Determine if the show action must be included in the list of authorized actions for the route. This option is used when the actions option is set to false.
Possible values:
<true | false>
Default:
true

route_name > options > segment_names

Defines the words to use in the url patterns for the edit and new actions.
Default:
{ edit: edit, new: new }

route_name > options > with_wildcard_routes

This option allows (or not) for any action to be accessed via two wildcard routes: one for a single object, and another for object collections.
Possible values:
<true | false>
Default:
false

route_name > options > route_class

This option overrides the default route object used for the collection.
Default:
sfObjectRoute (for sfObjectRouteCollection), sfDoctrineRoute (for sfDoctrineRouteCollection), sfPropelRoute (for sfPropelRouteCollection)

route_name > options > collection_actions

Defines an array of additional actions available for the collection routes. The keys are the action names and the values are the valid methods for that action:
articles:
  options:
    collection_actions: { filter: post, filterBis: [post, get] }
    # ...
Default:
An empty array

route_name > options > object_actions

Defines an associative array of additional actions available for the object routes. The keys are the action names and the values are the valid methods for that action:
articles:
  options:
    object_actions: { publish: put, publishBis: [post, put] }
    # ...
Default:
An empty array

Routing requirements

route_name > options > requirements

Defines an array of requirements that must be satisfied by the url variables.

route_name > options > requirements > variable_name

Each url pattern variable can be validated by a regular expression defined using the requirements entry of a route definition, The keys are the url variables and the values are regular expressions that the variable values must match:
job:
  class:   sfDoctrineRouteCollection
  options:
    model:          Job
    column:         token
    prefix_path:    /:sf_culture/job
    module:         sfJob
    requirements:
      token: \w+
      sf_culture: (?:lt|en)
The above requirements entry forces the token to contain only word characters (letters, digits, and underscores). If not, the route won't match and the routing system will keep on looking for a match in the following rules.

Model methods

route_name > options > model_methods

Defines the methods to call to retrieve the object(s) from the model (see the method option of sfObjectRoute). This is actually an array defining the list and the object methods.

route_name > options > model_methods > list

Defines the method to call on the model class to retrieve the objects associated with this route. This must be a static method. The method is called with the parameters of the parsed route as an argument.

route_name > options > model_methods > object

Defines the method to call on the model class to retrieve the object associated with this route. This must be a static method. The method is called with the parameters of the parsed route as an argument.

Questions and Feedback

If you find a problem with the documentation, have a technical question or have a suggestion you can post to the user mailing-list, or refer to a community page.