From 4557feea8c1baeac70f6322439dad6b35a40e3bb Mon Sep 17 00:00:00 2001
From: Ryan Weaver <ryan@thatsquality.com>
Date: Wed, 15 May 2013 22:04:52 -0500
Subject: [PATCH] [#2619] Tweaks for new proxy/lazy services entry (cherry
 picked from commit d7ea3a540a5dc425bf1d16f4113746975404da38)

---
 .../dependency_injection/lazy_services.rst    | 55 ++++++++++++++-----
 1 file changed, 40 insertions(+), 15 deletions(-)

diff --git a/components/dependency_injection/lazy_services.rst b/components/dependency_injection/lazy_services.rst
index 599d503f7e6..88ad0c51f59 100644
--- a/components/dependency_injection/lazy_services.rst
+++ b/components/dependency_injection/lazy_services.rst
@@ -7,19 +7,41 @@ Lazy Services
 .. versionadded:: 2.3
    Lazy services were added in Symfony 2.3.
 
-Configuring lazy services
--------------------------
+Why 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 some cases, you may want to inject a service that is a bit heavy to instantiate,
+but is not always used inside your object. For example, imagine you have
+a ``NewsletterManager`` and you inject a ``mailer`` service into it. Only
+a few methods on your ``NewsletterManager`` actually use the ``mailer``,
+but even when you don't need it, a ``mailer`` service is always instantiated
+in order to construct your ``NewsletterManager``.
 
-In order to have services to lazily instantiate, you will first need to install
+Configuring lazy services is one answer to this. With a lazy service, a "proxy"
+of the ``mailer`` service is actually injected. It looks and acts just like
+the ``mailer``, except that the ``mailer`` isn't actually instantiated until
+you interact with the proxy in some way.
+
+Installation
+------------
+
+In order to use the lazy service instantiation, 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:
+.. note::
+
+    If you're using the full-stack framework, this package is not included
+    and needs to be added to ``composer.json`` and installed (which is what
+    the above command does).
+
+Configuration
+-------------
+
+You can mark the service as ``lazy`` by manipulating its definition:
 
 .. configuration-block::
 
@@ -44,24 +66,27 @@ 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.
+At this point the retrieved ``$service`` should be a virtual `proxy`_ with
+the same signature of the class representing the service. You can also inject
+the service just like normal into other services. The object that's actually
+injected will be the proxy.
 
 .. 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.
+    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.
+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`_.
+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
+.. _`ProxyManager bridge`: https://github.com/symfony/symfony/tree/master/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
\ No newline at end of file