minor #14981 Update documentation for deprecated "session.storage" service (jderusse)

This PR was merged into the 5.3-dev branch.

Discussion
----------

Update documentation for deprecated "session.storage" service

Fixes #14979

Commits
-------

4a3a987 Update documentation for deprecated "session.storage" service

Author: javiereguiluz

reference/configuration/framework.rst

@@ -269,7 +269,7 @@ Configuration
   * `save_path`_
   * `sid_length`_
   * `sid_bits_per_character`_
-  * `storage_id`_
+  * `storage_factory_id`_
   * `use_cookies`_
 
 * `test`_
@@ -1443,19 +1443,24 @@ errors.
 session
 ~~~~~~~
 
-storage_id
-..........
+storage_factory_id
+..................
 
-**type**: ``string`` **default**: ``'session.storage.native'``
+**type**: ``string`` **default**: ``'session.storage.factory.native'``
 
-The service ID used for storing the session. The ``session.storage`` service
-alias will be set to this service. The class has to implement
-:class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\SessionStorageInterface`.
+The service ID used for creatig the ``SessionStorageInterface`` that will store
+the session. The ``session.storage.factory`` service alias will be set to this
+service. The class has to implement
+:class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\SessionStorageFactoryInterface`.
 To see a list of all available storages, run:
 
 .. code-block:: terminal
 
-    $ php bin/console debug:container session.storage.
+    $ php bin/console debug:container session.storage.factory.
+
+.. versionadded:: 5.3
+
+    The ``storage_factory_id`` option was introduced in Symfony 5.3.
 
 .. _config-framework-session-handler-id:
 

session.rst

@@ -185,33 +185,51 @@ your ``Session`` object with the default ``AttributeBag`` by the ``NamespacedAtt
     .. code-block:: yaml
 
         # config/services.yaml
-        session_listener:
+        session.factory:
             autoconfigure: true
-            class: App\EventListener\SessionListener
+            class: App\Session\SessionFactory
             arguments:
-            - !service_locator
-                logger: '@?logger'
-                session_collector: '@?data_collector.request.session_collector'
-                session_storage: '@session.storage'
-                session_attributes: '@session.namespacedattributebag'
-            - '%kernel.debug%'
+            - '@request_stack'
+            - '@session.storage.factory'
+            - ['@session_listener', 'onSessionUsage']
+            - '@session.namespacedattributebag'
 
         session.namespacedattributebag:
             class: Symfony\Component\HttpFoundation\Session\Attribute\NamespacedAttributeBag
 
 .. code-block:: php
 
-    namespace App\EventListener;
+    namespace App\Session;
 
+    use Symfony\Component\HttpFoundation\RequestStack;
+    use Symfony\Component\HttpFoundation\Session\Attribute\NamespacedAttributeBag;
     use Symfony\Component\HttpFoundation\Session\Session;
     use Symfony\Component\HttpFoundation\Session\SessionInterface;
-    use Symfony\Component\HttpKernel\EventListener\AbstractSessionListener;
+    use Symfony\Component\HttpFoundation\Session\Storage\SessionStorageFactoryInterface;
 
-    class SessionListener extends AbstractSessionListener
+    class SessionFactory
     {
-        protected function getSession(): ?SessionInterface
+        private $requestStack;
+        private $storageFactory;
+        private $usageReporter;
+        private $sessionAttributes;
+
+        public function __construct(RequestStack $requestStack, SessionStorageFactoryInterface $storageFactory, callable $usageReporter, NamespacedAttributeBag $sessionAttributes)
+        {
+            $this->requestStack = $requestStack;
+            $this->storageFactory = $storageFactory;
+            $this->usageReporter = $usageReporter;
+            $this->sessionAttributes = $sessionAttributes;
+        }
+
+        public function createSession(): SessionInterface
         {
-            return new Session($this->container->get('session_storage'), $this->container->get('session_attributes'));
+            return new Session(
+                $this->storageFactory->createStorage($this->requestStack->getMasterRequest()),
+                $this->sessionAttributes,
+                null,
+                $this->usageReporter
+            );
         }
     }
 

session/php_bridge.rst

@@ -18,7 +18,7 @@ for the ``handler_id``:
         # config/packages/framework.yaml
         framework:
             session:
-                storage_id: session.storage.php_bridge
+                storage_factory_id: session.storage.factory.php_bridge
                 handler_id: ~
 
     .. code-block:: xml
@@ -32,7 +32,7 @@ for the ``handler_id``:
                 https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <framework:config>
-                <framework:session storage-id="session.storage.php_bridge"
+                <framework:session storage-factory-id="session.storage.factory.php_bridge"
                     handler-id="null"
                 />
             </framework:config>
@@ -43,7 +43,7 @@ for the ``handler_id``:
         // config/packages/framework.php
         $container->loadFromExtension('framework', [
             'session' => [
-                'storage_id' => 'session.storage.php_bridge',
+                'storage_factory_id' => 'session.storage.factory.php_bridge',
                 'handler_id' => null,
             ],
         ]);
@@ -60,7 +60,7 @@ the example below:
         # config/packages/framework.yaml
         framework:
             session:
-                storage_id: session.storage.php_bridge
+                storage_factory_id: session.storage.factory.php_bridge
                 handler_id: session.handler.native_file
 
     .. code-block:: xml
@@ -85,7 +85,7 @@ the example below:
         // config/packages/framework.php
         $container->loadFromExtension('framework', [
             'session' => [
-                'storage_id' => 'session.storage.php_bridge',
+                'storage_factory_id' => 'session.storage.factory.php_bridge',
                 'handler_id' => 'session.storage.native_file',
             ],
         ]);