feature #7322 Added docs for the SessionValueResolver (iltar)

This PR was squashed before being merged into the master branch (closes #7322).

Discussion
----------

Added docs for the SessionValueResolver

Explains the functionality added in symfony/symfony#21164

Commits
-------

88b740e Added docs for the SessionValueResolver

Author: xabbuh

controller.rst

@@ -344,18 +344,17 @@ Symfony provides a nice session object that you can use to store information
 about the user between requests. By default, Symfony stores the attributes in a
 cookie by using native PHP sessions.
 
-To retrieve the session, call
-:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::getSession`
-method on the ``Request`` object. This method returns a
-:class:`Symfony\\Component\\HttpFoundation\\Session\\SessionInterface` with easy
-methods for storing and fetching things from the session::
 
-    use Symfony\Component\HttpFoundation\Request;
+.. versionadded:: 3.3
+    The ability to request a ``Session`` in actions was introduced in Symfony 3.3.
 
-    public function indexAction(Request $request)
-    {
-        $session = $request->getSession();
+To retrieve the session, add the :class:`Symfony\\Component\\HttpFoundation\\Session\\SessionInterface`
+type-hint to your argument and Symfony will provide you with a session::
 
+    use Symfony\Component\HttpFoundation\Session\SessionInterface;
+
+    public function indexAction(SessionInterface $session)
+    {
         // store an attribute for reuse during a later user request
         $session->set('foo', 'bar');
 
@@ -368,6 +367,23 @@ methods for storing and fetching things from the session::
 
 Stored attributes remain in the session for the remainder of that user's session.
 
+.. tip::
+
+    Every ``SessionInterface`` implementation is supported. If you have your
+    own implementation, type-hint this in the arguments instead.
+
+As a developer, you might prefer not to extend the ``Controller``. To use the
+flash message functionality, you can request the flash bag from the
+:class:`Symfony\\Component\\HttpFoundation\\Session\\Session`::
+
+    use Symfony\Component\HttpFoundation\Session\Session;
+
+    public function indexAction(Session $session)
+    {
+        // getFlashBag is not available in the SessionInterface and requires the Session
+        $flashBag = $session->getFlashBag();
+    }
+
 .. index::
    single: Session; Flash messages
 

controller/argument_value_resolver.rst

@@ -15,6 +15,9 @@ functionality.
 Functionality Shipped with the HttpKernel
 -----------------------------------------
 
+.. versionadded:: 3.3
+    The ``SessionValueResolver`` was introduced in Symfony 3.3.
+
 Symfony ships with four value resolvers in the HttpKernel component:
 
 :class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentResolver\\RequestAttributeValueResolver`
@@ -24,6 +27,11 @@ Symfony ships with four value resolvers in the HttpKernel component:
     Injects the current ``Request`` if type-hinted with ``Request`` or a class
     extending ``Request``.
 
+:class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentResolver\\SessionValueResolver`
+    Injects the configured session class extending ``SessionInterface`` if
+    type-hinted with ``SessionInterface`` or a class extending
+    ``SessionInterface``.
+
 :class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentResolver\\DefaultValueResolver`
     Will set the default value of the argument if present and the argument
     is optional.

quick_tour/the_controller.rst

@@ -299,12 +299,10 @@ in a cookie by using native PHP sessions.
 Storing and retrieving information from the session can be easily achieved
 from any controller::
 
-    use Symfony\Component\HttpFoundation\Request;
+    use Symfony\Component\HttpFoundation\Session\Session;
 
-    public function indexAction(Request $request)
+    public function indexAction(Session $session)
     {
-        $session = $request->getSession();
-
         // store an attribute for reuse during a later user request
         $session->set('foo', 'bar');
 
@@ -319,7 +317,7 @@ You can also store "flash messages" that will auto-delete after the next
 request. They are useful when you need to set a success message before
 redirecting the user to another page (which will then show the message)::
 
-    public function indexAction(Request $request)
+    public function indexAction()
     {
         // ...