Merge remote-tracking branch 'upstream/3.3' into 3.3

Author: javiereguiluz

bundles/extension.rst

@@ -129,11 +129,9 @@ read more about it, see the ":doc:`/bundles/configuration`" article.
 Adding Classes to Compile
 -------------------------
 
-.. note::
-
-    The ``addClassesToCompile()`` method was deprecated in Symfony 3.3, and will
-    be removed in Symfony 4.0. If you want to use this method and be compatible
-    with Symfony 4.0, check to see if the method exists before calling it.
+.. versionadded:: 3.3
+    This technique is discouraged and the ``addClassesToCompile()`` method was
+    deprecated in Symfony 3.3 because modern PHP versions make it unnecessary.
 
 Symfony creates a big ``classes.php`` file in the cache directory to aggregate
 the contents of the PHP classes that are used in every request. This reduces the

components/dependency_injection.rst

@@ -5,8 +5,9 @@
 The DependencyInjection Component
 =================================
 
-    The DependencyInjection component allows you to standardize and centralize
-    the way objects are constructed in your application.
+    The DependencyInjection component implements a `PSR-11`_ compatible service
+    container that allows you to standardize and centralize the way objects are
+    constructed in your application.
 
 For an introduction to Dependency Injection and service containers see
 :doc:`/service_container`.
@@ -305,4 +306,5 @@ Learn More
     /components/dependency_injection/*
     /service_container/*
 
+.. _`PSR-11`: http://www.php-fig.org/psr/psr-11/
 .. _Packagist: https://packagist.org/packages/symfony/dependency-injection

components/yaml.rst

@@ -368,6 +368,12 @@ Add the ``--format`` option to get the output in JSON format:
 
     $ php lint.php path/to/file.yml --format json
 
+.. tip::
+
+    The linting command will also report any deprecations in the checked
+    YAML files. This may for example be useful for recognizing deprecations of
+    contents of YAML files during automated tests.
+
 Learn More
 ----------
 

debug/debugging.rst

@@ -61,6 +61,11 @@ cache files, or you can change the extension used by Symfony for these files::
 
     $kernel->loadClassCache('classes', '.php.cache');
 
+.. versionadded:: 3.3
+    The ``loadClassCache()`` was deprecated in Symfony 3.3 and removed in
+    Symfony 4.0. No alternative is provided because this feature is useless
+    when using PHP 7 or higher.
+
 Useful Debugging Commands
 -------------------------
 

deployment/platformsh.rst

@@ -64,6 +64,7 @@ Platform.sh how to deploy your application (read more about
     mounts:
         '/var/cache': 'shared:files/cache'
         '/var/logs': 'shared:files/logs'
+        '/var/sessions': 'shared:files/sessions'
 
     # The hooks that will be performed when the package is deployed.
     hooks:

frontend/encore/shared-entry.rst

@@ -32,7 +32,7 @@ on your page before any other JavaScript file:
 .. code-block:: twig
 
     <!-- these two files now must be included in every page -->
-    <script src="{{ asset('build/manifest.json') }}"></script>
+    <script src="{{ asset('build/manifest.js') }}"></script>
     <script src="{{ asset('build/vendor.js') }}"></script>
 
     <!-- here you link to the specific JS files needed by the current page -->
@@ -42,7 +42,7 @@ on your page before any other JavaScript file:
     <link rel="stylesheet" href="{{ asset('build/vendor.css') }}" />
 
 The ``vendor.js`` file contains all the common code that has been extracted from
-the other files, so it's obvious that it must be included. The other file (``manifest.json``)
+the other files, so it's obvious that it must be included. The other file (``manifest.js``)
 is less obvious: it's needed so that Webpack knows how to load those shared modules.
 
 .. tip::

serializer/encoders.rst

@@ -23,10 +23,23 @@ You can add new encoders to a Serializer instance by using its second constructo
 Built-in Encoders
 -----------------
 
-Two encoders are used in the example above:
+The Serializer component provides built-in encoders:
 
-* :class:`Symfony\\Component\\Serializer\\Encoder\\XmlEncoder` to encode/decode XML
+* :class:`Symfony\\Component\\Serializer\\Encoder\\CsvEncoder` to encode/decode CSV
 * :class:`Symfony\\Component\\Serializer\\Encoder\\JsonEncoder` to encode/decode JSON
+* :class:`Symfony\\Component\\Serializer\\Encoder\\XmlEncoder` to encode/decode XML
+* :class:`Symfony\\Component\\Serializer\\Encoder\\YamlEncoder` to encode/decode Yaml
+
+.. versionadded:: 3.2
+    The :class:`Symfony\\Component\\Serializer\\Encoder\\CsvEncoder` and the
+    :class:`Symfony\\Component\\Serializer\\Encoder\\YamlEncoder` were introduced in
+    Symfony 3.2.
+
+The ``JsonEncoder``
+~~~~~~~~~~~~~~~~~~~
+
+The ``JsonEncoder`` encodes to and decodes from JSON strings, based on the PHP
+:phpfunction:`json_encode` and :phpfunction:`json_decode` functions.
 
 The ``XmlEncoder``
 ~~~~~~~~~~~~~~~~~~
@@ -56,8 +69,8 @@ Be aware that this encoder will consider keys beginning with ``@`` as attributes
     //     <foo bar="value" />
     // </response>
 
-The ``JsonEncoder``
+The ``YamlEncoder``
 ~~~~~~~~~~~~~~~~~~~
 
-The ``JsonEncoder`` is much simpler and is based on the PHP
-:phpfunction:`json_encode` and :phpfunction:`json_decode` functions.
+This encoder requires the :doc:`Yaml Component </components/yaml>` and
+transforms from and to Yaml.

service_container/3.3-di-changes.rst

@@ -22,6 +22,8 @@ which means it's always safe to upgrade across minor versions.
 All of the new features are **optional**: they are not enabled by default, so you
 need to actually change your configuration files to use them.
 
+.. _`service-33-default_definition`:
+
 The new Default services.yml File
 ---------------------------------
 
@@ -411,7 +413,7 @@ In general, the new best practice is to use normal constructor dependency inject
 4) Auto-tagging with autoconfigure
 ----------------------------------
 
-The last big change is the ``autoconfigure`` key, which is set to ``true`` under
+The fourth big change is the ``autoconfigure`` key, which is set to ``true`` under
 ``_defaults``. Thanks to this, the container will auto-tag services registered in
 this file. For example, suppose you want to create an event subscriber. First, you
 create the class::
@@ -468,6 +470,59 @@ Many autoconfigured tags have an optional priority. If you need to specify a pri
 (or any other optional tag attribute), no problem! Just :ref:`manually configure your service <services-manually-wire-args>`
 and add the tag. Your tag will take precedence over the one added by auto-configuration.
 
+5) Auto-configure with _instanceof
+----------------------------------
+
+And the final big change is ``_instanceof``. It acts as a default definition
+template (see `service-33-default_definition`_), but only for services whose
+class matches a defined one.
+
+This can be very useful when many services share some tag that cannot be
+inherited from an abstract definition:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/services.yml
+        services:
+            # ...
+
+            _instanceof:
+                class: AppBundle\Domain\LoaderInterface
+                public: true
+                tags: ['app.domain_loader']
+
+    .. 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>
+                <!-- ... -->
+
+                <instanceof id="AppBundle\Domain\LoaderInterface" public="true">
+                    <tag name="app.domain_loader" />
+                </instanceof>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/services.php
+        use AppBundle\Domain\LoaderInterface;
+
+        // ...
+
+        /* This method returns a child definition to define the default
+           configuration of the given class or interface */
+        $container->registerForAutoconfiguration(LoaderInterface::class)
+            ->addTag('app.domain_loader');
+
 What about Performance
 ----------------------
 

service_container/service_locators.rst

@@ -14,6 +14,9 @@ A real-world example are applications that implement the `Command pattern`_
 using a CommandBus to map command handlers by Command class names and use them
 to handle their respective command when it is asked for::
 
+    // src/AppBundle/CommandBus.php
+    namespace AppBundle;
+
     // ...
     class CommandBus
     {
@@ -46,28 +49,29 @@ Considering that only one command is handled at a time, instantiating all the
 other command handlers is unnecessary. A possible solution to lazy-load the
 handlers could be to inject the whole dependency injection container::
 
-        use Symfony\Component\DependencyInjection\ContainerInterface;
+    // ...
+    use Symfony\Component\DependencyInjection\ContainerInterface;
 
-        class CommandBus
-        {
-            private $container;
+    class CommandBus
+    {
+        private $container;
 
-            public function __construct(ContainerInterface $container)
-            {
-                $this->container = $container;
-            }
+        public function __construct(ContainerInterface $container)
+        {
+            $this->container = $container;
+        }
 
-            public function handle(Command $command)
-            {
-                $commandClass = get_class($command);
+        public function handle(Command $command)
+        {
+            $commandClass = get_class($command);
 
-                if ($this->container->has($commandClass)) {
-                    $handler = $this->container->get($commandClass);
+            if ($this->container->has($commandClass)) {
+                $handler = $this->container->get($commandClass);
 
-                    return $handler->handle($command);
-                }
+                return $handler->handle($command);
             }
         }
+    }
 
 However, injecting the entire container is discouraged because it gives too
 broad access to existing services and it hides the actual dependencies of the
@@ -87,8 +91,8 @@ option to include as many services as needed to it and add the
 
     .. code-block:: yaml
 
+        // app/config/services.yml
         services:
-
             app.command_handler_locator:
                 class: Symfony\Component\DependencyInjection\ServiceLocator
                 tags: ['container.service_locator']
@@ -99,6 +103,7 @@ option to include as many services as needed to it and add the
 
     .. 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"
@@ -119,6 +124,7 @@ option to include as many services as needed to it and add the
 
     .. code-block:: php
 
+        // app/config/services.php
         use Symfony\Component\DependencyInjection\ServiceLocator;
         use Symfony\Component\DependencyInjection\Reference;
 
@@ -144,13 +150,14 @@ Now you can use the service locator injecting it in any other service:
 
     .. code-block:: yaml
 
+        // app/config/services.yml
         services:
-
             AppBundle\CommandBus:
                 arguments: ['@app.command_handler_locator']
 
     .. 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"
@@ -159,19 +166,18 @@ Now you can use the service locator injecting it in any other service:
             <services>
 
                 <service id="AppBundle\CommandBus">
-                    <argument type="service" id="app.command_handler.locator" />
+                    <argument type="service" id="app.command_handler_locator" />
                 </service>
 
             </services>
         </container>
 
     .. code-block:: php
 
+        // app/config/services.php
         use AppBundle\CommandBus;
         use Symfony\Component\DependencyInjection\Reference;
 
-        //...
-
         $container
             ->register(CommandBus::class)
             ->setArguments(array(new Reference('app.command_handler_locator')))
@@ -185,7 +191,7 @@ Now you can use the service locator injecting it in any other service:
 Usage
 -----
 
-Back to the previous CommandBus example, it looks like this when using the
+Back to the previous ``CommandBus`` example, it looks like this when using the
 service locator::
 
     // ...

service_container/tags.rst

@@ -72,7 +72,7 @@ that it implements ``Twig_ExtensionInterface``) and adds the tag for you.
 
 .. tip::
 
-    To apply a tag to all your autoconfigured services extending a class or an
+    To apply a tag to all your autoconfigured services extending a class or implementing an
     interface, call the :method:`Symfony\\Component\\DependencyInjection\\ContainerBuilder::registerForAutoconfiguration`
     method in an :doc:`extension </bundles/extension>` or from your kernel::