[HttpKernel] Document the MapSessionParameter value resolver

Author: jtattevin

controller/value_resolver.rst

@@ -110,6 +110,13 @@ Symfony ships with the following value resolvers in the
     Injects a service if type-hinted with a valid service class or interface. This
     works like :doc:`autowiring </service_container/autowiring>`.
 
+:class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentResolver\\SessionParameterValueResolver.php`
+    Pass a session parameter to a controller argument.
+
+    Because this is a :ref:`targeted value resolver <value-resolver-targeted>`,
+    you'll have to use the :ref:`MapSessionParameter <session-passing-session-parameter>` attribute
+    in order to use this resolver.
+
 :class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentResolver\\SessionValueResolver`
     Injects the configured session class implementing ``SessionInterface`` if
     type-hinted with ``SessionInterface`` or a class implementing

session.rst

@@ -1328,6 +1328,47 @@ has to return an integer which will be used as TTL.
             // Inject whatever dependencies you need to be able to resolve a TTL for the current session
             ->args([service('security')]);
 
+
+.. _session-passing-session-parameter:
+
+Passing a session parameter to a controller argument
+----------------------------------------------------
+
+A possibility is to pass a session parameter to a controller argument.
+Let's say you declare the following DTO ::
+
+    namespace App\Model;
+
+    class PreferenceDTO
+    {
+        public bool $enableNotification = true;
+        public string $locale = "en";
+    }
+
+You can then use the :class:`Symfony\\Component\\HttpKernel\\Attribute\\MapSessionParameter`
+attribute in your controller::
+
+    use App\Model\PreferenceDTO;
+    use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\HttpKernel\Attribute\MapSessionParameter;
+
+    // ...
+
+    public function dashboard(
+        #[MapSessionParameter] PreferenceDTO $preferencesDTO
+    ): Response
+    {
+        // ...
+    }
+
+The method will then receive an instance of your DTO linked with the session.
+Value set in this object will be persisted in session and will be available for reading later.
+
+The name of the parameter is used as the session key.
+
+This attribute work with classes and interfaces.
+If you use an interface, you must provide a default value or make the parameter nullable, if the session isn't set, it will not be possible to create a new instance when resolving the value.
+
 .. _locale-sticky-session:
 
 Making the Locale "Sticky" during a User's Session