https://github.com/symfony/symfony-docs/pull/11574#discussion_r289199817

Author: MatTheCat

security/firewall_restriction.rst

@@ -9,11 +9,22 @@ result of a request matcher: the first firewall matching the request will handle
 
 The last firewall can be configured without any matcher to handle every incoming request.
 
-Restricting by Service
-----------------------
+Restricting by Configuration
+----------------------------
 
-You can configure any service implementing :class:`Symfony\\Component\\HttpFoundation\\RequestMatcherInterface`
-as ``request_matcher``.
+Most of the time you don't need to create matchers yourself as Symfony can do it for you based on the
+firewall configuration.
+
+.. note::
+
+    You can use any of the following restrictions individually or mix them together to get
+    your desired firewall configuration.
+
+Restricting by Path
+~~~~~~~~~~~~~~~~~~~
+
+This is the default restriction and restricts a firewall to only be initialized if the request path
+matches the configured ``pattern``.
 
 .. configuration-block::
 
@@ -25,7 +36,7 @@ as ``request_matcher``.
         security:
             firewalls:
                 secured_area:
-                    request_matcher: app.firewall.secured_area.request_matcher
+                    pattern: ^/admin
                     # ...
 
     .. code-block:: xml
@@ -40,7 +51,7 @@ as ``request_matcher``.
 
             <config>
                 <!-- ... -->
-                <firewall name="secured_area" request-matcher="app.firewall.secured_area.request_matcher">
+                <firewall name="secured_area" pattern="^/admin">
                     <!-- ... -->
                 </firewall>
             </config>
@@ -54,28 +65,23 @@ as ``request_matcher``.
         $container->loadFromExtension('security', [
             'firewalls' => [
                 'secured_area' => [
-                    'request_matcher' => 'app.firewall.secured_area.request_matcher',
+                    'pattern' => '^/admin',
                     // ...
                 ],
             ],
         ]);
 
-However in most cases you don't need to create these matchers yourself as Symfony can do it for you based
-on the firewall configuration.
-
-Restricting by Configuration
-----------------------------
-
-.. note::
-
-    You can use any of the following restrictions individually or mix them together to get
-    your desired firewall configuration.
+The ``pattern`` is a regular expression. In this example, the firewall will only be
+activated if the path starts (due to the ``^`` regex character) with ``/admin``. If
+the path does not match this pattern, the firewall will not be activated and subsequent
+firewalls will have the opportunity to be matched for this request.
 
-Restricting by Path
+Restricting by Host
 ~~~~~~~~~~~~~~~~~~~
 
-This is the default restriction and restricts a firewall to only be initialized if the request path
-matches the configured ``pattern``.
+If matching against the ``pattern`` only is not enough, the request can also be matched against
+``host``. When the configuration option ``host`` is set, the firewall will be restricted to
+only initialize if the host from the request matches against the configuration.
 
 .. configuration-block::
 
@@ -87,7 +93,7 @@ matches the configured ``pattern``.
         security:
             firewalls:
                 secured_area:
-                    pattern: ^/admin
+                    host: ^admin\.example\.com$
                     # ...
 
     .. code-block:: xml
@@ -102,7 +108,7 @@ matches the configured ``pattern``.
 
             <config>
                 <!-- ... -->
-                <firewall name="secured_area" pattern="^/admin">
+                <firewall name="secured_area" host="^admin\.example\.com$">
                     <!-- ... -->
                 </firewall>
             </config>
@@ -116,23 +122,24 @@ matches the configured ``pattern``.
         $container->loadFromExtension('security', [
             'firewalls' => [
                 'secured_area' => [
-                    'pattern' => '^/admin',
+                    'host' => '^admin\.example\.com$',
                     // ...
                 ],
             ],
         ]);
 
-The ``pattern`` is a regular expression. In this example, the firewall will only be
-activated if the path starts (due to the ``^`` regex character) with ``/admin``. If
-the path does not match this pattern, the firewall will not be activated and subsequent
-firewalls will have the opportunity to be matched for this request.
+The ``host`` (like the ``pattern``) is a regular expression. In this example,
+the firewall will only be activated if the host is equal exactly (due to
+the ``^`` and ``$`` regex characters) to the hostname ``admin.example.com``.
+If the hostname does not match this pattern, the firewall will not be activated
+and subsequent firewalls will have the opportunity to be matched for this
+request.
 
-Restricting by Host
-~~~~~~~~~~~~~~~~~~~
+Restricting by HTTP Methods
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If matching against the ``pattern`` only is not enough, the request can also be matched against
-``host``. When the configuration option ``host`` is set, the firewall will be restricted to
-only initialize if the host from the request matches against the configuration.
+The configuration option ``methods`` restricts the initialization of the firewall to
+the provided HTTP methods.
 
 .. configuration-block::
 
@@ -144,7 +151,7 @@ only initialize if the host from the request matches against the configuration.
         security:
             firewalls:
                 secured_area:
-                    host: ^admin\.example\.com$
+                    methods: [GET, POST]
                     # ...
 
     .. code-block:: xml
@@ -159,7 +166,7 @@ only initialize if the host from the request matches against the configuration.
 
             <config>
                 <!-- ... -->
-                <firewall name="secured_area" host="^admin\.example\.com$">
+                <firewall name="secured_area" methods="GET,POST">
                     <!-- ... -->
                 </firewall>
             </config>
@@ -173,24 +180,22 @@ only initialize if the host from the request matches against the configuration.
         $container->loadFromExtension('security', [
             'firewalls' => [
                 'secured_area' => [
-                    'host' => '^admin\.example\.com$',
+                    'methods' => ['GET', 'POST'],
                     // ...
                 ],
             ],
         ]);
 
-The ``host`` (like the ``pattern``) is a regular expression. In this example,
-the firewall will only be activated if the host is equal exactly (due to
-the ``^`` and ``$`` regex characters) to the hostname ``admin.example.com``.
-If the hostname does not match this pattern, the firewall will not be activated
-and subsequent firewalls will have the opportunity to be matched for this
-request.
+In this example, the firewall will only be activated if the HTTP method of the
+request is either ``GET`` or ``POST``. If the method is not in the array of the
+allowed methods, the firewall will not be activated and subsequent firewalls will again
+have the opportunity to be matched for this request.
 
-Restricting by HTTP Methods
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Restricting by Service
+----------------------
 
-The configuration option ``methods`` restricts the initialization of the firewall to
-the provided HTTP methods.
+If the above options don't fit your needs you can configure any service implementing
+:class:`Symfony\\Component\\HttpFoundation\\RequestMatcherInterface` as ``request_matcher``.
 
 .. configuration-block::
 
@@ -202,7 +207,7 @@ the provided HTTP methods.
         security:
             firewalls:
                 secured_area:
-                    methods: [GET, POST]
+                    request_matcher: app.firewall.secured_area.request_matcher
                     # ...
 
     .. code-block:: xml
@@ -217,7 +222,7 @@ the provided HTTP methods.
 
             <config>
                 <!-- ... -->
-                <firewall name="secured_area" methods="GET,POST">
+                <firewall name="secured_area" request-matcher="app.firewall.secured_area.request_matcher">
                     <!-- ... -->
                 </firewall>
             </config>
@@ -231,13 +236,8 @@ the provided HTTP methods.
         $container->loadFromExtension('security', [
             'firewalls' => [
                 'secured_area' => [
-                    'methods' => ['GET', 'POST'],
+                    'request_matcher' => 'app.firewall.secured_area.request_matcher',
                     // ...
                 ],
             ],
         ]);
-
-In this example, the firewall will only be activated if the HTTP method of the
-request is either ``GET`` or ``POST``. If the method is not in the array of the
-allowed methods, the firewall will not be activated and subsequent firewalls will again
-have the opportunity to be matched for this request.