From d9050a56d6a2574b0be48c6a907dff647fb22f03 Mon Sep 17 00:00:00 2001 From: Fabien Potencier Date: Sun, 8 Sep 2013 08:30:32 +0200 Subject: [PATCH] added documentation for the new request_stack service --- book/service_container.rst | 38 +++++++++++++++++++++------ cookbook/service_container/scopes.rst | 16 +++++------ 2 files changed, 37 insertions(+), 17 deletions(-) diff --git a/book/service_container.rst b/book/service_container.rst index c8e64bc7c4f..d24b77d95d6 100644 --- a/book/service_container.rst +++ b/book/service_container.rst @@ -270,14 +270,6 @@ looks up the value of each parameter and uses it in the service definition. http://symfony.com/?foo=%%s&bar=%%d -.. caution:: - - You may receive a - :class:`Symfony\\Component\\DependencyInjection\\Exception\\ScopeWideningInjectionException` - when passing the ``request`` service as an argument. To understand this - problem better and learn how to solve it, refer to the cookbook article - :doc:`/cookbook/service_container/scopes`. - The purpose of parameters is to feed information into services. Of course there was nothing wrong with defining the service without using any parameters. Parameters, however, have several advantages: @@ -762,6 +754,36 @@ Injecting the dependency by the setter method just needs a change of syntax: and "setter injection". The Symfony2 service container also supports "property injection". +Injecting the Request +~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 2.4 + The ``request_stack`` service was introduced in version 2.4. + +Almost all Symfony2 built-in services behave in the same way: a single +instance is created by the container which it returns whenever you get it or +when it is injected into another service. There is one exception in a standard +Symfony2 application: the ``request`` service. + +If you try to inject the ``request`` into a service, you will probably receive +a +:class:`Symfony\\Component\\DependencyInjection\\Exception\\ScopeWideningInjectionException` +exception. That's because the ``request`` can **change** during the life-time +of a container (when a sub-request is created for instance). + +As of Symfony 2.4, instead of injecting the ``request`` service, you should +inject the ``request_stack`` service instead and access the Request by calling +the ``getCurrentRequest()`` method. For earlier versions, or if you want to +understand this problem better, refer to the cookbook article +:doc:`/cookbook/service_container/scopes`. + +.. tip:: + + If you define a controller as a service then you can get the ``Request`` + object without injecting the container by having it passed in as an + argument of your action method. See + :ref:`book-controller-request-argument` for details. + Making References Optional -------------------------- diff --git a/cookbook/service_container/scopes.rst b/cookbook/service_container/scopes.rst index 8f5e8af0cfe..68a301a1101 100644 --- a/cookbook/service_container/scopes.rst +++ b/cookbook/service_container/scopes.rst @@ -6,8 +6,13 @@ How to work with Scopes This entry is all about scopes, a somewhat advanced topic related to the :doc:`/book/service_container`. If you've ever gotten an error mentioning -"scopes" when creating services, or need to create a service that depends -on the ``request`` service, then this entry is for you. +"scopes" when creating services, then this entry is for you. + +.. note:: + + If you are trying to inject the ``request`` service, the simple solution + is to inject the ``request_stack`` service instead and access the current + Request by calling the ``getCurrentRequest()`` method. Understanding Scopes -------------------- @@ -337,10 +342,3 @@ The service config for this class would look something like this: Injecting the whole container into a service is generally not a good idea (only inject what you need). - -.. tip:: - - If you define a controller as a service then you can get the ``Request`` - object without injecting the container by having it passed in as an - argument of your action method. See - :ref:`book-controller-request-argument` for details.