Merge branch '4.4' into 5.0

javiereguiluz · javiereguiluz · commit b5079ba1f936 · 2020-07-15T10:32:12.000+02:00
* 4.4:
  Updated some config file paths
  Use "closure-style" PHP configuration format in code examples
  [Security] Mention the feature to use a custom AccessDecisionManager
  Update bundles.rst
  [Console] Update input.rst
diff --git a/bundles.rst b/bundles.rst
@@ -31,7 +31,7 @@ file::
         Symfony\Bundle\SwiftmailerBundle\SwiftmailerBundle::class => ['all' => true],
         Doctrine\Bundle\DoctrineBundle\DoctrineBundle::class => ['all' => true],
         Sensio\Bundle\FrameworkExtraBundle\SensioFrameworkExtraBundle::class => ['all' => true],
-        // this bundle is enabled only in 'dev'  and 'test', so you can't use it in 'prod'
+        // this bundle is enabled only in 'dev' and 'test', so you can't use it in 'prod'
         Symfony\Bundle\WebProfilerBundle\WebProfilerBundle::class => ['dev' => true, 'test' => true],
     ];
 
diff --git a/configuration.rst b/configuration.rst
@@ -120,12 +120,15 @@ configuration files, even if they use a different format:
     .. code-block:: php
 
         // config/services.php
-        $loader->import('legacy_config.xml');
-        // the third optional argument of import() is 'ignore_errors', which
-        // silently discards errors if the loaded file doesn't exist
-        $loader->import('my_config_file.yaml', null, true);
-        // glob expressions are also supported to load multiple files
-        $loader->import('/etc/myapp/*.yaml');
+        namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+
+        return static function (ContainerConfigurator $container) {
+            $container->import('legacy_config.php');
+            // ignore_errors (3rd parameter) silently discards errors if the loaded file doesn't exist
+            $container->import('my_config_file.xml', null, true);
+            // glob expressions are also supported to load multiple files
+            $container->import('/etc/myapp/*.yaml');
+        };
 
         // ...
 
@@ -209,24 +212,29 @@ reusable configuration value. By convention, parameters are defined under the
     .. code-block:: php
 
         // config/services.php
-        // the parameter name is an arbitrary string (the 'app.' prefix is recommended
-        // to better differentiate your parameters from Symfony parameters).
-        $container->setParameter('app.admin_email', 'something@example.com');
+        namespace Symfony\Component\DependencyInjection\Loader\Configurator;
 
-        // boolean parameters
-        $container->setParameter('app.enable_v2_protocol', true);
+        use App\Entity\BlogPost;
 
-        // array/collection parameters
-        $container->setParameter('app.supported_locales', ['en', 'es', 'fr']);
+        return static function (ContainerConfigurator $container) {
+            $container->parameters()
+                // the parameter name is an arbitrary string (the 'app.' prefix is recommended
+                // to better differentiate your parameters from Symfony parameters).
+                ->set('app.admin_email', 'something@example.com')
 
-        // binary content parameters (use the PHP escape sequences)
-        $container->setParameter('app.some_parameter', 'This is a Bell char: \x07');
+                // boolean parameters
+                ->set('app.enable_v2_protocol', true)
 
-        // PHP constants as parameter values
-        use App\Entity\BlogPost;
+                // array/collection parameters
+                ->set('app.supported_locales', ['en', 'es', 'fr'])
 
-        $container->setParameter('app.some_constant', GLOBAL_CONSTANT);
-        $container->setParameter('app.another_constant', BlogPost::MAX_ITEMS);
+                // binary content parameters (use the PHP escape sequences)
+                ->set('app.some_parameter', 'This is a Bell char: \x07')
+
+                // PHP constants as parameter values
+                ->set('app.some_constant', GLOBAL_CONSTANT)
+                ->set('app.another_constant', BlogPost::MAX_ITEMS);
+        };
 
         // ...
 
@@ -278,12 +286,17 @@ configuration file using a special syntax: wrap the parameter name in two ``%``
     .. code-block:: php
 
         // config/packages/some_package.php
-        $container->loadFromExtension('some_package', [
-            // any string surrounded by two % is replaced by that parameter value
-            'email_address' => '%app.admin_email%',
+        namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+
+        return static function (ContainerConfigurator $container) {
+            $container->extension('some_package', [
+                // any string surrounded by two % is replaced by that parameter value
+                'email_address' => '%app.admin_email%',
+
+                // ...
+            ]);
+        };
 
-            // ...
-        ]);
 
 .. note::
 
@@ -310,7 +323,12 @@ configuration file using a special syntax: wrap the parameter name in two ``%``
         .. code-block:: php
 
             // config/services.php
-            $container->setParameter('url_pattern', 'http://symfony.com/?foo=%%s&amp;bar=%%d');
+            namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+
+            return static function (ContainerConfigurator $container) {
+                $container->parameters()
+                    ->set('url_pattern', 'http://symfony.com/?foo=%%s&amp;bar=%%d');
+            };
 
 .. include:: /components/dependency_injection/_imports-parameters-note.rst.inc
 
@@ -478,12 +496,16 @@ This example shows how you could configure the database connection using an env
     .. code-block:: php
 
         // config/packages/doctrine.php
-        $container->loadFromExtension('doctrine', [
-            'dbal' => [
-                // by convention the env var names are always uppercase
-                'url' => '%env(resolve:DATABASE_URL)%',
-            ]
-        ]);
+        namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+
+        return static function (ContainerConfigurator $container) {
+            $container->extension('doctrine', [
+                'dbal' => [
+                    // by convention the env var names are always uppercase
+                    'url' => '%env(resolve:DATABASE_URL)%',
+                ]
+            ]);
+        };
 
 .. seealso::
 
@@ -772,13 +794,18 @@ doesn't work for parameters:
     .. code-block:: php
 
         // config/services.php
+        namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+
         use App\Service\MessageGenerator;
-        use Symfony\Component\DependencyInjection\Reference;
 
-        $container->setParameter('app.contents_dir', '...');
+        return static function (ContainerConfigurator $container) {
+            $container->parameters()
+                ->set('app.contents_dir', '...');
 
-        $container->getDefinition(MessageGenerator::class)
-            ->setArgument('$contentsDir', '%app.contents_dir%');
+            $container->services()
+                ->get(MessageGenerator::class)
+                    ->arg('$contentsDir', '%app.contents_dir%');
+        };
 
 If you inject the same parameters over and over again, use the
 ``services._defaults.bind`` option instead. The arguments defined in that option are
@@ -824,18 +851,22 @@ whenever a service/controller defines a ``$projectDir`` argument, use this:
     .. code-block:: php
 
         // config/services.php
+        namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+
         use App\Controller\LuckyController;
         use Psr\Log\LoggerInterface;
         use Symfony\Component\DependencyInjection\Reference;
 
-        $container->register(LuckyController::class)
-            ->setPublic(true)
-            ->setBindings([
-                // pass this value to any $projectDir argument for any service
-                // that's created in this file (including controller arguments)
-                '$projectDir' => '%kernel.project_dir%',
-            ])
-        ;
+        return static function (ContainerConfigurator $container) {
+            $container->services()
+                ->set(LuckyController::class)
+                    ->public()
+                    ->args([
+                        // pass this value to any $projectDir argument for any service
+                        // that's created in this file (including controller arguments)
+                        '$projectDir' => '%kernel.project_dir%',
+                    ]);
+        };
 
 .. seealso::
 
diff --git a/console/input.rst b/console/input.rst
@@ -106,7 +106,7 @@ There are three argument variants you can use:
     The argument can contain any number of values. For that reason, it must be
     used at the end of the argument list.
 
-You can combine ``IS_ARRAY`` with ``REQUIRED`` and ``OPTIONAL`` like this::
+You can combine ``IS_ARRAY`` with ``REQUIRED`` or ``OPTIONAL`` like this::
 
     $this
         // ...
diff --git a/security/voters.rst b/security/voters.rst
@@ -313,3 +313,49 @@ security configuration:
                 'allow_if_all_abstain' => false,
             ],
         ]);
+
+Custom Access Decision Strategy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If none of the built-in strategies fits your use case, define the ``service``
+option to use a custom service as the Access Decision Manager (your service
+must implement the :class:`Symfony\\Component\\Security\\Core\\Authorization\\AccessDecisionManagerInterface`):
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/security.yaml
+        security:
+            access_decision_manager:
+                service: App\Security\MyCustomAccessDecisionManager
+                # ...
+
+    .. code-block:: xml
+
+        <!-- config/packages/security.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd"
+        >
+
+            <config>
+                <access-decision-manager
+                    service="App\Security\MyCustomAccessDecisionManager"/>
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // config/packages/security.php
+        use App\Security\MyCustomAccessDecisionManager;
+
+        $container->loadFromExtension('security', [
+            'access_decision_manager' => [
+                'service' => MyCustomAccessDecisionManager::class,
+                // ...
+            ],
+        ]);
