From dd7c90bb9f13addc4632d658f6352a497fcb150c Mon Sep 17 00:00:00 2001
From: WouterJ <waldio.webdesign@gmail.com>
Date: Sun, 16 Jun 2013 13:07:07 +0200
Subject: [PATCH] Documented synthetic services

---
 components/dependency_injection/advanced.rst | 46 ++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/components/dependency_injection/advanced.rst b/components/dependency_injection/advanced.rst
index 677c3541ce4..284f8a58375 100644
--- a/components/dependency_injection/advanced.rst
+++ b/components/dependency_injection/advanced.rst
@@ -59,6 +59,52 @@ below) to access this service (via the alias).
 
    Services are by default public.
 
+Synthetic Services
+------------------
+
+Synthetic services are services that are injected into the container instead
+of being created by the container.
+
+For instance, the ``request`` service which is injected in the
+:method:`HttpKernel::handle() <Symfony\\Component\\HttpKernel\\HttpKernel::handle>`
+method when entering the request :doc:`scope </cookbook/service_container/scopes>`.
+The class does not exist when there is no request, so it can't be included in
+the container configuration. Also, the service should be different for every
+subrequest in the application.
+
+To create a synthetic service, set ``synthetic`` to ``true``:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        services:
+            request:
+                synthetic: true
+
+    .. code-block:: xml
+
+        <service id="request"
+            synthetic="true" />
+
+    .. code-block:: php
+
+        use Symfony\Component\DependencyInjection\Definition;
+
+        // ...
+        $container->setDefinition('request', new Definition())
+            ->setSynthetic(true);
+
+As you see, only the ``synthetic`` option is set. All other options are only used
+to configure the container how a service is created by the container. As the
+service isn't created by the container, these options are omitted.
+
+Now, you can inject the class by using
+:method:`Symfony\\Component\\DependencyInjection\\ContainerBuilder::set`::
+
+    // ...
+    $container->set('request', new MyRequest(...));
+
 Aliasing
 --------