Improved "optional argument" documentation"

Expanded the documentation for the "on invalid" behaviors for optional
arguments.

Author: dantleech

book/service_container.rst

@@ -751,8 +751,13 @@ Sometimes, one of your services may have an optional dependency, meaning
 that the dependency is not required for your service to work properly. In
 the example above, the ``app.mailer`` service *must* exist, otherwise an exception
 will be thrown. By modifying the ``app.newsletter_manager`` service definition,
-you can make this reference optional. The container will then inject it if
-it exists and do nothing if it doesn't:
+you can make this reference optional, there are two strategies for doing this:
+
+Ignoring missing dependencies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In the following example the container will inject the service if it exists
+and ommit the argument if it doesn't:
 
 .. configuration-block::
 
@@ -812,6 +817,64 @@ allow for an optional dependency::
             // ...
         }
 
+The "ignore" behavior when a service does not exist is context sensitive:
+
+- When used as a standard argument, the argument will be set to ``null``;
+- When used within a method call, the method call itself will be removed;
+- When used on a collection argument, the argument will be removed.
+
+Setting missing dependencies to null
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want to explicitly set the argument to ``null`` in the event that the
+service does not exist (rather than for example, removing the item from a
+collection), you may use the ``null`` strategy as follows:
+
+.. configuration-block::
+
+    .. 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="app.mailer">
+                <!-- ... -->
+                </service>
+
+                <service id="app.newsletter_manager" class="AppBundle\Newsletter\NewsletterManager">
+                    <argument type="service" id="app.mailer" on-invalid="null" />
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/services.php
+        use Symfony\Component\DependencyInjection\Definition;
+        use Symfony\Component\DependencyInjection\Reference;
+        use Symfony\Component\DependencyInjection\ContainerInterface;
+
+        $container->setDefinition('app.mailer', ...);
+
+        $container->setDefinition('app.newsletter_manager', new Definition(
+            'AppBundle\Newsletter\NewsletterManager',
+            array(
+                new Reference(
+                    'app.mailer',
+                    ContainerInterface::NULL_ON_INVALID_REFERENCE
+                )
+            )
+        ));
+
+.. note::
+
+    The "null" strategy is not currently supported by the YAML driver.
+
 Core Symfony and Third-Party Bundle Services
 --------------------------------------------