Add "Handling decorations on non existent service"

Author: mtarld

service_container/service_decoration.rst

@@ -313,4 +313,105 @@ The generated code will be the following::
 
     $this->services[Foo::class] = new Baz(new Bar(new Foo()));
 
+Control the behavior when the decorated service does not exist
+-------------------
+
+Let's imagine you have a decorator that decorates a service defined in another bundle.
+If for some reasons, that bundle is missing, the ``decoration_on_decorated_invalid``
+option will allow you to handle the lack of decorated service.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/services.yaml
+        Foo: ~
+
+        Bar:
+            public: false
+            decorates: Foo
+            decoration_on_decorated_invalid: ignore
+            arguments: ['@Bar.inner']
+
+    .. code-block:: xml
+
+        <!-- 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 https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+                <service id="Foo"/>
+
+                <service id="Bar" decorates="Foo" decoration-on-decorated-invalid="ignore">
+                    <argument type="service" id="Bar.inner"/>
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // config/services.php
+        namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+
+        use Symfony\Component\DependencyInjection\ContainerInterface;
+
+        return function(ContainerConfigurator $configurator) {
+            $services = $configurator->services();
+
+            $services->set(Foo::class);
+
+            $services->set(Bar::class)
+                ->decorate(Foo::class, null, 0, ContainerInterface::IGNORE_ON_INVALID_REFERENCE)
+                ->args([ref(Bar::class.'.inner')]);
+
+            $services->set(Baz::class)
+                ->private()
+                ->decorate(Foo::class, null, 1)
+                ->args([ref(Baz::class.'.inner')]);
+        };
+
+Three different behaviors are available:
+
+* ``exception``: The default behavior. When used, a ``ServiceNotFoundException``
+  will be thrown telling that decorator's dependency is missing.
+* ``ignored``: Using that behavior, the container will remove either decorator
+  and decorated services.
+* ``nulled``: When used, the container will keep the decorator
+  service and will set the decorated one to `null`.
+
+.. tip::
+
+    When using ``nulled``, you may update the decorator's constructor in
+    order to make decorated dependency nullable. In this way, you will be able to
+    check the presence of decorated service in other methods.
+
+    .. code-block:: php
+
+        namespace App\Service;
+
+        use App\Service\OptionalDecoratedService;
+
+        class DecoratorService
+        {
+            private $decorated;
+
+            - public function __construct(OptionalDecoratedService $decorated)
+            + public function __construct(?OptionalDecoratedService $decorated)
+            {
+                $this->decorated = $decorated;
+            }
+
+            public function tellInterestingStuff(): string
+            {
+                + if (!$this->decorated) {
+                +     return 'Just one interesting thing';
+                + }
+
+                return $this->decorated->tellInterestingStuff().' + one more interesting thing';
+            }
+        }
+
 .. _`Decorator pattern`: https://en.wikipedia.org/wiki/Decorator_pattern