Merge branch '3.4' into 4.0

Author: wouterj

_build/redirection_map

@@ -386,3 +386,4 @@
 /request/load_balancer_reverse_proxy /deployment/proxies
 /quick_tour/the_controller /quick_tour/the_big_picture
 /quick_tour/the_view /quick_tour/flex_recipes
+/service_container/service_locators /service_container/service_subscribers_locators

components/var_dumper/advanced.rst

@@ -319,7 +319,7 @@ being cloned in an array. They are callables that accept five arguments:
 * a :class:`Symfony\\Component\\VarDumper\\Cloner\\Stub` object
   representing the main properties of the object (class, type, etc.);
 * true/false when the caster is called nested in a structure or not;
-* A bit field of :class:`Symfony\\Component\\VarDumper\\Caster\\Caster```::EXCLUDE_*``
+* A bit field of :class:`Symfony\\Component\\VarDumper\\Caster\\Caster` ``::EXCLUDE_*``
   constants.
 
 Here is a simple caster not doing anything::

frontend/encore/simple-example.rst

@@ -5,20 +5,20 @@ Imagine you have a simple project with one CSS and one JS file, organized into
 an ``assets/`` directory:
 
 * ``assets/js/app.js``
-* ``assets/css/app.scss``
+* ``assets/css/app.css``
 
 With Encore, you should think of CSS as a *dependency* of your JavaScript. This means,
 you will *require* whatever CSS you need from inside JavaScript:
 
 .. code-block:: javascript
 
     // assets/js/app.js
-    require('../css/app.scss');
+    require('../css/app.css');
 
     // ...rest of JavaScript code here
 
-With Encore, we can easily minify these files, pre-process ``app.scss``
-through Sass and a *lot* more.
+With Encore, we can easily minify these files, pre-process ``app.css``
+through PostCSS and a *lot* more.
 
 Configuring Encore/Webpack
 --------------------------
@@ -41,12 +41,10 @@ Inside, use Encore to help generate your Webpack configuration.
         // will create public/build/app.js and public/build/app.css
         .addEntry('app', './assets/js/app.js')
 
-        // allow sass/scss files to be processed
-        .enableSassLoader()
-
         // allow legacy applications to use $/jQuery as a global variable
         .autoProvidejQuery()
 
+        // enable source maps during development
         .enableSourceMaps(!Encore.isProduction())
 
         // empty the outputPath dir before each build
@@ -57,13 +55,16 @@ Inside, use Encore to help generate your Webpack configuration.
 
         // create hashed filenames (e.g. app.abc123.css)
         // .enableVersioning()
+
+        // allow sass/scss files to be processed
+        // .enableSassLoader()
     ;
 
     // export the final configuration
     module.exports = Encore.getWebpackConfig();
 
-This is already a rich setup: it outputs 2 files, uses the Sass pre-processor and
-enables source maps to help debugging.
+This is already a rich setup: it outputs 2 files and enables source maps
+to help debugging.
 
 .. _encore-build-assets:
 
@@ -89,9 +90,6 @@ To build the assets, use the ``encore`` executable:
 
     Re-run ``encore`` each time you update your ``webpack.config.js`` file.
 
-Actually, to use ``enableSassLoader()``, you'll need to install a few
-more packages. But Encore will tell you *exactly* what you need.
-
 After running one of these commands, you can now add ``script`` and ``link`` tags
 to the new, compiled assets (e.g. ``/build/app.css`` and ``/build/app.js``).
 In Symfony, use the ``asset()`` helper:
@@ -111,6 +109,34 @@ In Symfony, use the ``asset()`` helper:
         </body>
     </html>
 
+Using Sass
+----------
+
+Instead of using plain CSS you can also use Sass. In order to do so, change the
+extension of the ``app.css`` file to ``.sass`` or ``.scss`` (based on the syntax
+you want to use):
+
+.. code-block:: diff
+
+    // assets/js/app.js
+    - require('../css/app.css');
+    + require('../css/app.scss');
+
+And enable the Sass pre-processor:
+
+.. code-block:: diff
+
+    // webpack.config.js
+    Encore
+        // ...
+
+        // allow sass/scss files to be processed
+    -    // .enableSassLoader()
+    +    .enableSassLoader()
+
+Using ``enableSassLoader()`` requires to install additional packages, but Encore
+will tell you *exactly* which ones when running it.
+
 Requiring JavaScript Modules
 ----------------------------
 

service_container/lazy_services.rst

@@ -6,7 +6,7 @@ Lazy Services
 
 .. seealso::
 
-    Another way to inject services lazily is via a :doc:`service locator </service_container/service_locators>`.
+    Another way to inject services lazily is via a :doc:`service subscriber </service_container/service_subscribers_locators>`.
 
 Why Lazy Services?
 ------------------

service_container/service_locators.rst renamed to service_container/service_subscribers_locators.rst

@@ -1,8 +1,11 @@
 .. index::
-    single: DependencyInjection; Service Locators
+    single: DependencyInjection; Service Subscribers
 
-Service Locators
-================
+Service Subscribers & Locators
+==============================
+
+.. versionadded:: 3.3
+    Service subscribers and locators were introduced in Symfony 3.3.
 
 Sometimes, a service needs access to several other services without being sure
 that all of them will actually be used. In those cases, you may want the
@@ -77,15 +80,178 @@ However, injecting the entire container is discouraged because it gives too
 broad access to existing services and it hides the actual dependencies of the
 services.
 
-**Service Locators** are intended to solve this problem by giving access to a
-set of predefined services while instantiating them only when actually needed.
+**Service Subscribers** are intended to solve this problem by giving access to a
+set of predefined services while instantiating them only when actually needed
+through a **Service Locator**, a separate lazy-loaded container.
+
+Defining a Service Subscriber
+-----------------------------
+
+First, turn ``CommandBus`` into an implementation of :class:`Symfony\\Component\\DependencyInjection\\ServiceSubscriberInterface`.
+Use its ``getSubscribedServices()`` method to include as many services as needed
+in the service subscriber and change the type hint of the container to
+a PSR-11 ``ContainerInterface``::
+
+    // src/AppBundle/CommandBus.php
+    namespace AppBundle;
+
+    use AppBundle\CommandHandler\BarHandler;
+    use AppBundle\CommandHandler\FooHandler;
+    use Psr\Container\ContainerInterface;
+    use Symfony\Component\DependencyInjection\ServiceSubscriberInterface;
+
+    class CommandBus implements ServiceSubscriberInterface
+    {
+        private $locator;
+
+        public function __construct(ContainerInterface $locator)
+        {
+            $this->locator = $locator;
+        }
+
+        public static function getSubscribedServices()
+        {
+            return [
+                'AppBundle\FooCommand' => FooHandler::class,
+                'AppBundle\BarCommand' => BarHandler::class,
+            ];
+        }
+
+        public function handle(Command $command)
+        {
+            $commandClass = get_class($command);
+
+            if ($this->locator->has($commandClass)) {
+                $handler = $this->locator->get($commandClass);
+
+                return $handler->handle($command);
+            }
+        }
+    }
+
+.. tip::
+
+    If the container does *not* contain the subscribed services, double-check
+    that you have :ref:`autoconfigure <services-autoconfigure>` enabled. You
+    can also manually add the ``container.service_subscriber`` tag.
+
+The injected service is an instance of :class:`Symfony\\Component\\DependencyInjection\\ServiceLocator`
+which implements the PSR-11 ``ContainerInterface``, but it is also a callable::
+
+    // ...
+    $locateHandler = $this->locator;
+    $handler = $locateHandler($commandClass);
+
+    return $handler->handle($command);
+
+Including Services
+------------------
+
+In order to add a new dependency to the service subscriber, use the
+``getSubscribedServices()`` method to add service types to include in the
+service locator::
+
+    use Psr\Log\LoggerInterface;
+
+    public static function getSubscribedServices()
+    {
+        return [
+            // ...
+            LoggerInterface::class,
+        ];
+    }
+
+Service types can also be keyed by a service name for internal use::
+
+    use Psr\Log\LoggerInterface;
+
+    public static function getSubscribedServices()
+    {
+        return [
+            // ...
+            'logger' => LoggerInterface::class,
+        ];
+    }
+
+Optional Services
+~~~~~~~~~~~~~~~~~
+
+For optional dependencies, prepend the service type with a ``?`` to prevent
+errors if there's no matching service found in the service container::
+
+    use Psr\Log\LoggerInterface;
+
+    public static function getSubscribedServices()
+    {
+        return [
+            // ...
+            '?'.LoggerInterface::class,
+        ];
+    }
+
+.. note::
+
+    Make sure an optional service exists by calling ``has()`` on the service
+    locator before calling the service itself.
+
+Aliased Services
+~~~~~~~~~~~~~~~~
+
+By default, autowiring is used to match a service type to a service from the
+service container. If you don't use autowiring or need to add a non-traditional
+service as a dependency, use the ``container.service_subscriber`` tag to map a
+service type to a service.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        // app/config/services.yml
+        services:
+            AppBundle\CommandBus:
+                tags:
+                    - { name: 'container.service_subscriber', key: 'logger', id: 'monolog.logger.event' }
+
+    .. code-block:: xml
+
+        <!-- app/config/services.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+
+                <service id="AppBundle\CommandBus">
+                    <tag name="container.service_subscriber" key="logger" id="monolog.logger.event" />
+                </service>
+
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/services.php
+        use AppBundle\CommandBus;
+
+        // ...
+
+        $container
+            ->register(CommandBus::class)
+            ->addTag('container.service_subscriber', array('key' => 'logger', 'id' => 'monolog.logger.event'))
+        ;
+
+.. tip::
+
+    The ``key`` attribute can be omitted if the service name internally is the
+    same as in the service container.
 
 Defining a Service Locator
 --------------------------
 
-First, define a new service for the service locator. Use its ``arguments``
-option to include as many services as needed to it and add the
-``container.service_locator`` tag to turn it into a service locator:
+To manually define a service locator, create a new service definition and add
+the ``container.service_locator`` tag to it. Use its ``arguments`` option to
+include as many services as needed in it.
 
 .. configuration-block::
 
@@ -128,7 +294,7 @@ option to include as many services as needed to it and add the
         use Symfony\Component\DependencyInjection\ServiceLocator;
         use Symfony\Component\DependencyInjection\Reference;
 
-        //...
+        // ...
 
         $container
             ->register('app.command_handler_locator', ServiceLocator::class)
@@ -144,7 +310,7 @@ option to include as many services as needed to it and add the
     The services defined in the service locator argument must include keys,
     which later become their unique identifiers inside the locator.
 
-Now you can use the service locator injecting it in any other service:
+Now you can use the service locator by injecting it in any other service:
 
 .. configuration-block::
 
@@ -188,45 +354,4 @@ Now you can use the service locator injecting it in any other service:
     If the service locator is not intended to be used by multiple services, it's
     better to create and inject it as an anonymous service.
 
-Usage
------
-
-Back to the previous ``CommandBus`` example, it looks like this when using the
-service locator::
-
-    // ...
-    use Psr\Container\ContainerInterface;
-
-    class CommandBus
-    {
-        /**
-         * @var ContainerInterface
-         */
-        private $handlerLocator;
-
-        // ...
-
-        public function handle(Command $command)
-        {
-            $commandClass = get_class($command);
-
-            if (!$this->handlerLocator->has($commandClass)) {
-                return;
-            }
-
-            $handler = $this->handlerLocator->get($commandClass);
-
-            return $handler->handle($command);
-        }
-    }
-
-The injected service is an instance of :class:`Symfony\\Component\\DependencyInjection\\ServiceLocator`
-which implements the PSR-11 ``ContainerInterface``, but it is also a callable::
-
-    // ...
-    $locateHandler = $this->handlerLocator;
-    $handler = $locateHandler($commandClass);
-
-    return $handler->handle($command);
-
 .. _`Command pattern`: https://en.wikipedia.org/wiki/Command_pattern