[HttpKernel] Document the MapSessionContext 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`
+    Map type-hinted object into the session.
+
+    Because this is a :ref:`targeted value resolver <value-resolver-targeted>`,
+    you'll have to use the :ref:`MapSessionParameter <session-mapping-session-context>` 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,44 @@ 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-mapping-session-parameter:
+
+Mapping the session to a DTO object
+-----------------------------------
+
+A possibility is to map the current session into an object that will read from/write to the session.
+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.
+
 .. _locale-sticky-session:
 
 Making the Locale "Sticky" during a User's Session