symfony · gondo · May 7, 2013 · May 8, 2013 · May 9, 2013 · May 10, 2013
diff --git a/components/dependency_injection/index.rst b/components/dependency_injection/index.rst
@@ -14,5 +14,6 @@
     configurators
     parentservices
     advanced
+    lazy_services
     workflow
 
diff --git a/components/dependency_injection/lazy_services.rst b/components/dependency_injection/lazy_services.rst
@@ -0,0 +1,67 @@
+.. index::
+   single: Dependency Injection; Lazy Services
+
+Lazy Services
+=============
+
+.. versionadded:: 2.3
+   Lazy services were added in Symfony 2.3.
+
+Configuring lazy services
+-------------------------
+
+In some particular cases where a very heavy service is always requested,
+but not always used, you may want to mark it as ``lazy`` to delay its instantiation.
+
+In order to have services to lazily instantiate, you will first need to install
+the `ProxyManager bridge`_:
+
+.. code-block:: bash
+    $ php composer.phar require symfony/proxy-manager-bridge:2.3.*
+
+You can mark the service as ``lazy`` by manipulating its definitions:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        services:
+           foo:
+             class: Acme\Foo
+             lazy: true
+
+    .. code-block:: xml
+
+        <service id="foo" class="Acme\Foo" lazy="true" />
+
+    .. code-block:: php
+
+        $definition = new Definition('Acme\Foo');
+        $definition->setLazy(true);
+        $container->setDefinition('foo', $definition);
+
+You can then require the service from the container::
+
+    $service = $container->get('foo');
+
+At this point the retrieved ``$service`` should be a virtual `proxy`_ with the same
+signature of the class representing the service.
+
+.. note::
+
+    If you don't install the `ProxyManager bridge`_, the container will just skip
+    over the ``lazy`` flag and simply instantiate the service as it would normally do.
+
+The proxy gets initialized and the actual service is instantiated as soon as you interact
+in any way with this object.
+
+Additional Resources
+--------------------
+
+You can read more about how proxies are instantiated, generated and initialized in
+the `documentation of ProxyManager`_.
+
+
+.. _`ProxyManager bridge`: https://github.com/symfony/symfony/tree/2.3/src/Symfony/Bridge/ProxyManager
+.. _`proxy`: http://en.wikipedia.org/wiki/Proxy_pattern
+.. _`documentation of ProxyManager`: https://github.com/Ocramius/ProxyManager/blob/master/docs/lazy-loading-value-holder.md
diff --git a/components/map.rst.inc b/components/map.rst.inc
@@ -39,6 +39,7 @@
   * :doc:`/components/dependency_injection/configurators`
   * :doc:`/components/dependency_injection/parentservices`
   * :doc:`/components/dependency_injection/advanced`
+  * :doc:`/components/dependency_injection/lazy_services`
   * :doc:`/components/dependency_injection/workflow`
 
 * **DOM Crawler**