[#14219] Merged the two IPs examples

wouterj · wouterj · commit 14d9473720bf · 2020-10-03T15:40:46.000+02:00
diff --git a/security/access_control.rst b/security/access_control.rst
@@ -25,7 +25,7 @@ access control should be used on this request. The following ``access_control``
 options are used for matching:
 
 * ``path``: a regular expression (without delimiters)
-* ``ip`` or ``ips``: netmasks are also supported
+* ``ip`` or ``ips``: netmasks are also supported (can be a comma-separated string)
 * ``port``: an integer
 * ``host``: a regular expression
 * ``methods``: one or many methods
@@ -37,6 +37,9 @@ Take the following ``access_control`` entries as an example:
     .. code-block:: yaml
 
         # config/packages/security.yaml
+        parameters:
+            env(TRUSTED_IPS): '10.0.0.1, 10.0.0.2'
+
         security:
             # ...
             access_control:
@@ -45,6 +48,10 @@ Take the following ``access_control`` entries as an example:
                 - { path: '^/admin', roles: ROLE_USER_HOST, host: symfony\.com$ }
                 - { path: '^/admin', roles: ROLE_USER_METHOD, methods: [POST, PUT] }
 
+                # ips can be comma-separated, which is especially useful when using env variables
+                - { path: '^/admin', roles: ROLE_USER_IP, ips: '%env(TRUSTED_IPS)%' }
+                - { path: '^/admin', roles: ROLE_USER_IP, ips: [127.0.0.1, ::1, '%env(TRUSTED_IPS)%'] }
+
     .. code-block:: xml
 
         <!-- config/packages/security.xml -->
@@ -57,18 +64,31 @@ Take the following ``access_control`` entries as an example:
                 http://symfony.com/schema/dic/security
                 https://symfony.com/schema/dic/security/security-1.0.xsd">
 
+            <srv:parameters>
+                <srv:parameter key="env(TRUSTED_IPS)">10.0.0.1, 10.0.0.2</parameter>
+            </srv:parameters>
+
             <config>
                 <!-- ... -->
                 <rule path="^/admin" role="ROLE_USER_IP" ip="127.0.0.1"/>
                 <rule path="^/admin" role="ROLE_USER_PORT" ip="127.0.0.1" port="8080"/>
                 <rule path="^/admin" role="ROLE_USER_HOST" host="symfony\.com$"/>
                 <rule path="^/admin" role="ROLE_USER_METHOD" methods="POST, PUT"/>
+
+                <!-- ips can be comma-separated, which is especially useful when using env variables -->
+                <rule path="^/admin" role="ROLE_USER_IP" ip="%env(TRUSTED_IPS)%"/>
+                <rule path="^/admin" role="ROLE_USER_IP">
+                    <ip>127.0.0.1</ip>
+                    <ip>::1</ip>
+                    <ip>%env(TRUSTED_IPS)%</ip>
+                </rule>
             </config>
         </srv:container>
 
     .. code-block:: php
 
         // config/packages/security.php
+        $container->setParameter('env(TRUSTED_IPS)', '10.0.0.1, 10.0.0.2');
         $container->loadFromExtension('security', [
             // ...
             'access_control' => [
@@ -92,10 +112,30 @@ Take the following ``access_control`` entries as an example:
                     'path' => '^/admin',
                     'roles' => 'ROLE_USER_METHOD',
                     'methods' => 'POST, PUT',
-                ]
+                ],
+
+                // ips can be comma-separated, which is especially useful when using env variables
+                [
+                    'path' => '^/admin',
+                    'roles' => 'ROLE_USER_IP',
+                    'ips' => '%env(TRUSTED_IPS)%',
+                ],
+                [
+                    'path' => '^/admin',
+                    'roles' => 'ROLE_USER_IP',
+                    'ips' => [
+                        '127.0.0.1',
+                        '::1',
+                        '%env(TRUSTED_IPS)%',
+                    ],
+                ],
             ],
         ]);
 
+.. versionadded:: 5.2
+
+    Support for comma-separated IP addresses was introduced in Symfony 5.2.
+
 For each incoming request, Symfony will decide which ``access_control``
 to use based on the URI, the client's IP address, the incoming host name,
 and the request method. Remember, the first rule that matches is used, and
@@ -133,73 +173,6 @@ if ``ip``, ``port``, ``host`` or ``method`` are not specified for an entry, that
     :ref:`Deny access in PHP code <security-securing-controller>` if you want
     to disallow access based on ``$_GET`` parameter values.
 
-.. versionadded:: 5.2
-
-    Environment variables can be used to pass comma separated ip addresses
-    (as a single value or as one of array values):
-
-    .. configuration-block::
-
-        .. code-block:: yaml
-
-            # config/packages/security.yaml
-            parameters:
-                env(TRUSTED_IPS): '10.0.0.1, 10.0.0.2'
-            security:
-                # ...
-                access_control:
-                    - { path: '^/admin', ips: '%env(TRUSTED_IPS)%' }
-                    - { path: '^/admin', ips: [127.0.0.1, ::1, '%env(TRUSTED_IPS)%'] }
-
-        .. code-block:: xml
-
-            <!-- config/packages/security.xml -->
-            <?xml version="1.0" encoding="UTF-8"?>
-            <srv:container xmlns="http://symfony.com/schema/dic/security"
-                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-                xmlns:srv="http://symfony.com/schema/dic/services"
-                xsi:schemaLocation="http://symfony.com/schema/dic/services
-                    https://symfony.com/schema/dic/services/services-1.0.xsd
-                    http://symfony.com/schema/dic/security
-                    https://symfony.com/schema/dic/security/security-1.0.xsd">
-
-                <parameters>
-                    <parameter key="env(TRUSTED_IPS)">10.0.0.1, 10.0.0.2</parameter>
-                </parameters>
-
-                <config>
-                    <!-- ... -->
-                    <rule path="^/admin" ip="%env(TRUSTED_IPS)%"/>
-                    <rule path="^/admin">
-                        <ip>127.0.0.1</ip>
-                        <ip>::1</ip>
-                        <ip>%env(TRUSTED_IPS)%</ip>
-                    </rule>
-                </config>
-            </srv:container>
-
-        .. code-block:: php
-
-            // config/packages/security.php
-            $container->setParameter('env(TRUSTED_IPS)', '10.0.0.1, 10.0.0.2');
-            $container->loadFromExtension('security', [
-                // ...
-                'access_control' => [
-                    [
-                        'path' => '^/admin',
-                        'ips' => '%env(TRUSTED_IPS)%',
-                    ],
-                    [
-                        'path' => '^/admin',
-                        'ips' => [
-                            '127.0.0.1',
-                            '::1',
-                            '%env(TRUSTED_IPS)%',
-                        ],
-                    ],
-                ],
-            ]);
-
 .. _security-access-control-enforcement-options:
 
 2. Access Enforcement
