[DI] add docs for new namespace option

symfony · kbond · Aug 28, 2017 · Feb 9, 2018 · Sep 5, 2017 · 16e0cc74c06ead965e99c5e3a304496054f4ef65
commit 16e0cc74c06ead965e99c5e3a304496054f4ef65
diff --git a/service_container.rst b/service_container.rst
@@ -923,6 +923,31 @@ them will not cause the container to be rebuilt.
    means that all classes are "available to be *used* as services" without needing
    to be manually configured.

+.. sidebar:: The ``namespace`` Option
+
+    .. versionadded:: 3.4
+        The ``namespace`` option was added in Symfony 3.4.
+
+    When using the ``resource`` option in YAML, the namespace prefix can only be used once
+    per file when defining it as the ``id``. In order to have multiple definitions in the
+    same file with the same namespace prefix, you can use the ``namespace`` option. When
+    this option is used, the ``id`` can be anything as long as it is unique. For example,
+    you can define your services like this:
+
+    .. code-block:: yaml
+
+        # app/config/services.yml
+        services:
+            command_handlers:
+                namespace: App\Domain\
+                resource: ../../src/Domain/*/CommandHandler
+                tags: [command_handler]
+
+            event_subscribers:
+                namespace: App\Domain\
+                resource: ../../src/Domain/*/EventSubscriber
+                tags: [event_subscriber]
+
 .. _services-explicitly-configure-wire-services:

 Explicitly Configuring Services and Arguments