The routing.yml Configuration File
The routing.yml
configuration file allows the definition of routes.
The main routing.yml
configuration file for an application can be found in
the apps/APP_NAME/config/
directory.
The routing.yml
configuration file 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.
note
The routing.yml
configuration file is cached as a PHP file; the
process is automatically managed by the sfRoutingConfigHandler
class.
Route Classes
Route Configuration
The routing.yml
configuration file supports several settings to further
configure the routes. These settings are used by the sfRoutingConfigHandler
class to convert each route to an object.
class
Default: sfRoute
(or sfRouteCollection
if type
is collection
, see below)
The class
setting allows to change the route class to use for the route.
url
Default: /
The url
setting is 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
:
) - constants
- a wildcard (
*
) to match a sequence of key/value pairs
Each segment must be separated by one of the pre-defined separator
(/
or .
by default).
params
Default: An empty array
The params
setting defines an array of parameters associated with the route.
They can be default values for variables contained in the url
, or any other
variable relevant for this route.
param
Default: An empty array
This setting is equivalent to the params
settings.
options
Default: An empty array
The options
setting is 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.
requirements
Default: An empty array
The requirements
settings is 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.
tip
The regular expression will be included in a 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.
type
Default: null
If set to collection
, the route will be read as a route collection.
note
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.
sfRoute
All route classes extends the sfRoute
base class, which provides the
required settings to configure a route.
sfRequestRoute
sf_method
Default: get
The sf_method
option is to be used in the requirements
array. It enforces
the HTTP request in the route matching process.
sfObjectRoute
All the following options of sfObjectRoute
must be used inside the options
setting of the routing.yml
configuration file.
model
The model
option is mandatory and is the name of the model class to be
associated with the current route.
type
The type
option is mandatory and is 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.
method
The method
option is mandatory. It is 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.
allow_empty
Default: true
If the allow_empty
option is set to false
, the route will throw a 404
exception if no object is returned by the call to the model
method
.
convert
Default: toParams
The convert
option is 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).
sfPropelRoute
method_for_criteria
Default: doSelect
for collections, doSelectOne
for single objects
The method_for_criteria
option 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.
sfDoctrineRoute
method_for_query
Default: none
The method_for_query
option 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.
sfRouteCollection
The sfRouteCollection
base class represents a collection of routes.
sfObjectRouteCollection
model
The model
option is mandatory and is the name of the model class to be
associated with the current route.
actions
Default: false
The actions
option 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
.
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).
module
Default: The route name
The module
option defines the module name.
prefix_path
Default: /
followed by the route name
The prefix_path
option defines a prefix to prepend to all url
patterns. It
can be any valid pattern and can contain variables and several segments.
column
Default: id
The column
option defines the column of the model to use as the unique
identifier for the model object.
with_show
Default: true
The with_show
option is used when the actions
option is set to false
to
determine if the show
action must be included in the list of authorized
actions for the route.
segment_names
Default: array('edit' => 'edit', 'new' => 'new'),
The segment_names
defines the words to use in the url
patterns for the
edit
and new
actions.
model_methods
Default: An empty array
The model_methods
options 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:
model_methods: list: getObjects object: getObject
requirements
Default: \d+
for the column
The requirements
option defines an array of requirements to apply to the
route variables.
with_wildcard_routes
Default: false
The with_wildcard_routes
option allows for any action to be accessed via two
wildcard routes: one for a single object, and another for object collections.
route_class
Default: sfObjectRoute
The route_class
option can override the default route object used for the
collection.
collection_actions
Default: An empty array
The collection_actions
options defines an array of additional actions
available for the collection routes.
object_actions
Default: An empty array
The object_actions
options defines an array of additional actions available
for the object routes.
sfPropelRouteCollection
The sfPropelRouteCollection
route class extends the sfRouteCollection
, and
changes the default route class to sfPropelRoute
(see the route_class
option above).
sfDoctrineRouteCollection
The sfDoctrineRouteCollection
route class extends the sfRouteCollection
,
and changes the default route class to sfDoctrineRoute
(see the
route_class
option above).
This work is licensed under the Creative Commons Attribution-Share Alike 3.0 Unported License license.