feature #4017 Clarify that route defaults don't need a placeholder (i…

…amdto)

This PR was merged into the 2.3 branch.

Discussion
----------

Clarify that route defaults don't need a placeholder

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | no
| Applies to    | 2.3+
| Fixed tickets | #3960

Commits
-------

a18e5cc Clarify that route defaults don't need a placeholder

book/routing.rst

@@ -955,6 +955,10 @@ see :ref:`route-parameters-controller-arguments`.
     You can also use a special ``$_route`` variable, which is set to the
     name of the route that was matched.
 
+You can even add extra information to your route definition and access it
+within your controller. For more information on this topic,
+see :doc:`/cookbook/routing/extra_information`.
+
 .. index::
    single: Routing; Importing routing resources
 

cookbook/map.rst.inc

@@ -128,6 +128,7 @@
   * :doc:`/cookbook/routing/service_container_parameters`
   * :doc:`/cookbook/routing/custom_route_loader`
   * :doc:`/cookbook/routing/redirect_trailing_slash`
+  * :doc:`/cookbook/routing/extra_information`
 
 * :doc:`/cookbook/security/index`
 

cookbook/routing/extra_information.rst

@@ -0,0 +1,63 @@
+.. index::
+   single: Routing; Extra Information
+
+How to Pass Extra Information from a Route to a Controller
+==========================================================
+
+Parameters inside the ``defaults`` collection don't necessarily have to
+match a placeholder in the route ``path``. In fact, you can use the
+``defaults`` array to specify extra parameters that will then be accessible as
+arguments to your controller:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/routing.yml
+        blog:
+            path:      /blog/{page}
+            defaults:
+                _controller: AcmeBlogBundle:Blog:index
+                page:        1
+                title:       "Hello world!"
+
+    .. code-block:: xml
+
+        <!-- app/config/routing.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing
+                http://symfony.com/schema/routing/routing-1.0.xsd">
+
+            <route id="blog" path="/blog/{page}">
+                <default key="_controller">AcmeBlogBundle:Blog:index</default>
+                <default key="page">1</default>
+                <default key="title">Hello world!</default>
+            </route>
+        </routes>
+
+    .. code-block:: php
+
+        // app/config/routing.php
+        use Symfony\Component\Routing\RouteCollection;
+        use Symfony\Component\Routing\Route;
+
+        $collection = new RouteCollection();
+        $collection->add('blog', new Route('/blog/{page}', array(
+            '_controller' => 'AcmeBlogBundle:Blog:index',
+            'page'        => 1,
+            'title'       => 'Hello world!',
+        )));
+
+        return $collection;
+
+Now, you can access this extra parameter in your controller::
+
+    public function indexAction($page, $title)
+    {
+        // ...
+    }
+
+As you can see, the ``$title`` variable was never defined inside the route path,
+but you can still access its value from inside your controller.

cookbook/routing/index.rst

@@ -11,3 +11,4 @@ Routing
     service_container_parameters
     custom_route_loader
     redirect_trailing_slash
+    extra_information