Moved the section about matching based on expressions

Author: javiereguiluz

routing.rst

@@ -110,8 +110,8 @@ The route name (``blog_list``) is not important for now, but it will be essentia
 :ref:`generating URLs <routing-generating-urls>`. You only have to keep in mind
 that each route name must be unique in the application.
 
-Route HTTP Methods
-~~~~~~~~~~~~~~~~~~
+Matching HTTP Methods
+~~~~~~~~~~~~~~~~~~~~~
 
 By default, routes match any HTTP verb (``GET``, ``POST``, ``PUT``, etc.)
 Use the ``methods`` option to restrict the verbs each route should respond to:
@@ -200,6 +200,102 @@ Use the ``methods`` option to restrict the verbs each route should respond to:
     If you create your forms with :doc:`Symfony Forms </forms>` this is done
     automatically for you.
 
+Matching Expressions
+~~~~~~~~~~~~~~~~~~~~
+
+Use the ``condition`` option if you need some route to match based on some
+arbitrary matching logic:
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/Controller/DefaultController.php
+        namespace App\Controller;
+
+        use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+        use Symfony\Component\Routing\Annotation\Route;
+
+        class DefaultController extends AbstractController
+        {
+            /**
+             * @Route(
+             *     "/contact",
+             *     name="contact",
+             *     condition="context.getMethod() in ['GET', 'HEAD'] and request.headers.get('User-Agent') matches '/firefox/i'"
+             * )
+             *
+             * expressions can also include config parameters:
+             * condition: "request.headers.get('User-Agent') matches '%app.allowed_browsers%'"
+             */
+            public function contact()
+            {
+                // ...
+            }
+        }
+
+    .. code-block:: yaml
+
+        # config/routes.yaml
+        contact:
+            path:       /contact
+            controller: 'App\Controller\DefaultController::contact'
+            condition:  "context.getMethod() in ['GET', 'HEAD'] and request.headers.get('User-Agent') matches '/firefox/i'"
+            # expressions can also include config parameters:
+            # condition: "request.headers.get('User-Agent') matches '%app.allowed_browsers%'"
+
+    .. code-block:: xml
+
+        <!-- config/routes.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
+                https://symfony.com/schema/routing/routing-1.0.xsd">
+
+            <route id="contact" path="/contact" controller="App\Controller\DefaultController::contact">
+                <condition>context.getMethod() in ['GET', 'HEAD'] and request.headers.get('User-Agent') matches '/firefox/i'</condition>
+                <!-- expressions can also include config parameters: -->
+                <!-- <condition>request.headers.get('User-Agent') matches '%app.allowed_browsers%'</condition> -->
+            </route>
+        </routes>
+
+    .. code-block:: php
+
+        // config/routes.php
+        use App\Controller\DefaultController;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
+
+        return function (RoutingConfigurator $routes) {
+            $routes->add('contact', '')
+                ->controller([DefaultController::class, 'contact'])
+                ->condition('context.getMethod() in ["GET", "HEAD"] and request.headers.get("User-Agent") matches "/firefox/i"')
+                // expressions can also include config parameters:
+                // 'request.headers.get("User-Agent") matches "%app.allowed_browsers%"'
+            ;
+        };
+
+The value of the ``condition`` option is any valid
+:doc:`ExpressionLanguage expression </components/expression_language/syntax>`
+and can use and of these variables created by Symfony:
+
+``context``
+    An instance of :class:`Symfony\\Component\\Routing\\RequestContext`,
+    which holds the most fundamental information about the route being matched.
+
+``request``
+    The :ref:`Symfony Request <component-http-foundation-request>` object that
+    represents the current request.
+
+Behind the scenes, expressions are compiled down to raw PHP. Because of this,
+using the ``condition`` key causes no extra overhead beyond the time it takes
+for the underlying PHP to execute.
+
+.. caution::
+
+    Conditions are *not* taken into account when generating URLs (which is
+    explained later in this article).
+
 Debugging Routes
 ~~~~~~~~~~~~~~~~
 
@@ -679,105 +775,6 @@ parameter:
     To give a ``null`` default value to any parameter, add nothing after the
     ``?`` character (e.g. ``/blog/{page?}``).
 
-.. _routing-expression_parameters:
-
-Expression Parameters
-~~~~~~~~~~~~~~~~~~~~~
-
-Restricting routes via HTTP methods, host names and parameter validation is
-enough for most applications. However, if you need more flexibility to define
-arbitrary matching logic, you can use the ``condition`` option:
-
-.. configuration-block::
-
-    .. code-block:: php-annotations
-
-        // src/Controller/DefaultController.php
-        namespace App\Controller;
-
-        use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
-        use Symfony\Component\Routing\Annotation\Route;
-
-        class DefaultController extends AbstractController
-        {
-            /**
-             * @Route(
-             *     "/contact",
-             *     name="contact",
-             *     condition="context.getMethod() in ['GET', 'HEAD'] and request.headers.get('User-Agent') matches '/firefox/i'"
-             * )
-             *
-             * expressions can also include config parameters:
-             * condition: "request.headers.get('User-Agent') matches '%app.allowed_browsers%'"
-             */
-            public function contact()
-            {
-                // ...
-            }
-        }
-
-    .. code-block:: yaml
-
-        # config/routes.yaml
-        contact:
-            path:       /contact
-            controller: 'App\Controller\DefaultController::contact'
-            condition:  "context.getMethod() in ['GET', 'HEAD'] and request.headers.get('User-Agent') matches '/firefox/i'"
-            # expressions can also include config parameters:
-            # condition: "request.headers.get('User-Agent') matches '%app.allowed_browsers%'"
-
-    .. code-block:: xml
-
-        <!-- config/routes.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
-                https://symfony.com/schema/routing/routing-1.0.xsd">
-
-            <route id="contact" path="/contact" controller="App\Controller\DefaultController::contact">
-                <condition>context.getMethod() in ['GET', 'HEAD'] and request.headers.get('User-Agent') matches '/firefox/i'</condition>
-                <!-- expressions can also include config parameters: -->
-                <!-- <condition>request.headers.get('User-Agent') matches '%app.allowed_browsers%'</condition> -->
-            </route>
-        </routes>
-
-    .. code-block:: php
-
-        // config/routes.php
-        use App\Controller\DefaultController;
-        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
-
-        return function (RoutingConfigurator $routes) {
-            $routes->add('contact', '')
-                ->controller([DefaultController::class, 'contact'])
-                ->condition('context.getMethod() in ["GET", "HEAD"] and request.headers.get("User-Agent") matches "/firefox/i"')
-                // expressions can also include config parameters:
-                // 'request.headers.get("User-Agent") matches "%app.allowed_browsers%"'
-            ;
-        };
-
-The value of the ``condition`` option is any valid
-:doc:`ExpressionLanguage expression </components/expression_language/syntax>`
-where you can use any of these variables created by Symfony:
-
-``context``
-    An instance of :class:`Symfony\\Component\\Routing\\RequestContext`,
-    which holds the most fundamental information about the route being matched.
-
-``request``
-    The :ref:`Symfony Request <component-http-foundation-request>` object that
-    represents the current request.
-
-Behind the scenes, expressions are compiled down to raw PHP. Because of this,
-using the ``condition`` key causes no extra overhead beyond the time it takes
-for the underlying PHP to execute.
-
-.. caution::
-
-    Conditions are *not* taken into account when generating URLs (which is
-    explained later in this article).
-
 Parameter Conversion
 ~~~~~~~~~~~~~~~~~~~~