====== Symfony YAML Configuration Reference ====== =====The routing.yml configuration file===== In this article we assume that you are familiar with [[http://www.symfony-project.org/reference/1_4/en/02-YAML|The YAML Format]] and [[http://www.symfony-project.org/reference/1_4/en/03-Configuration-Files-Principles|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: 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: extra_parameters_as_query_string: 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: [, ...] # sfObjectRoute configuration options route_name: class: options: model: model_name type: method: model_method allow_empty: convert: method_name method_for_query: method_name method_for_criteria: method_name # sfObjectRouteCollection configuration options route_name: class: options: model: model_name actions: [, ...] module: module_name prefix_path: prefix_path_string column: column_name with_show: segment_names: { edit: edit_name, new: new_name } with_wildcard_routes: route_class: class_name collection_actions: { action1: [,...], action2: post, ... } object_actions: { action1: [,...], 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). ==== class ==== ** 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)// ==== url ==== ** 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: ///// ==== type ==== ** 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 ===== ==== param ==== ** 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. Default: //An empty array// === module === ** 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. Default: //An empty array// ==== 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: //// 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: //// Default: //true// ==== route_name > options > variable_regex ==== Defines regular expression used to adjust the characters allowed in your variable names. It's advisable to wrap the regex in "()". 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. Default: //An empty array// ==== 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: //[, ...]// Default: //get// ===== sfObjectRoute configuration options ===== ==== class ==== **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: //// ==== 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: //// ==== 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: //// 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. This method must be created in the model table class and takes //Doctrine_Query// object as a parameter, which you can modify further, eg.: class ObjectTable extends Doctrine_Table { public function retrieveObjectList(Doctrine_Query $q) { $rootAlias = $q->getRootAlias(); $q->leftJoin($rootAlias . '.ObjectCategory c'); return $q->execute(); } } 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: //// ==== 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// ==== prefix_path==== ** 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// ==== column==== ** route_name > options > column ** Defines the column of the model to use as the unique identifier for the model object. Default: //id// ==== with_show ==== ** 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: //// Default: //true// ==== segment_names ==== ** 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 }// ==== with_wildcard_routes ==== ** 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: //// Default: //false// ==== route_class==== ** 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)// ==== collection_actions ==== ** 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// ==== object_actions ==== ** 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 ===== ==== requirements ==== ** route_name > options > requirements ** Defines an array of requirements that must be satisfied by the //url// variables. ==== variable_name ==== ** 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 option ===== ==== 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. Default: //An empty array// ==== 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.