Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
[symfony#2619] Tweaks for new proxy/lazy services entry
(cherry picked from commit d7ea3a5)
  • Loading branch information
weaverryan committed Jun 10, 2013
1 parent bcc2fdd commit 4557fee
Showing 1 changed file with 40 additions and 15 deletions.
55 changes: 40 additions & 15 deletions components/dependency_injection/lazy_services.rst
Expand Up @@ -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::

Expand All @@ -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

0 comments on commit 4557fee

Please sign in to comment.