minor #9496 Adding MigratingSessionHandler docs (rossmotley, javiereguiluz)

javiereguiluz · javiereguiluz · commit 8dd54bbc4529 · 2018-05-24T10:44:12.000+02:00
This PR was merged into the 4.1 branch. Discussion ---------- Adding MigratingSessionHandler docs Adding `MigratingSessionHandler` documentation for symfony/symfony#26096 Commits ------- e93756f Added the versionadded directive 386f639 Reworded and simplified 7c8264d Update session_configuration.rst e971074 Update session_configuration.rst 91aa58d Adding MigratingSessionHandler docs
diff --git a/components/http_foundation/session_configuration.rst b/components/http_foundation/session_configuration.rst
@@ -73,6 +73,7 @@ easily serve as examples if you wish to write your own.
 
 * :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\PdoSessionHandler`
 * :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\MemcachedSessionHandler`
+* :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\MigratingSessionHandler`
 * :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\RedisSessionHandler`
 * :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\MongoDbSessionHandler`
 * :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\NullSessionHandler`
@@ -87,6 +88,32 @@ Example usage::
     $sessionStorage = new NativeSessionStorage(array(), new PdoSessionHandler($pdo));
     $session = new Session($sessionStorage);
 
+Migrating Between Save Handlers
+-------------------------------
+
+.. versionadded:: 4.1
+    The ``MigratingSessionHandler`` class was introduced in Symfony 4.1.
+
+If your application changes the way sessions are stored, use the
+:class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\MigratingSessionHandler`
+to migrate between old and new save handlers without losing session data.
+
+This is the recommended migration workflow:
+
+#. Switch to the migrating handler, with your new handler as the write-only one.
+   The old handler behaves as usual and sessions get written to the new one::
+
+       $sessionStorage = new MigratingSessionHandler($oldSessionStorage, $newSessionStorage);
+
+#. After your session gc period, verify that the data in the new handler is correct.
+#. Update the migrating handler to use the old handler as the write-only one, so
+   the sessions will now be read from the new handler. This step allows easier rollbacks::
+
+       $sessionStorage = new MigratingSessionHandler($newSessionStorage, $oldSessionStorage);
+
+#. After verifying that the sessions in your application are working, switch
+   from the migrating handler to the new handler.
+
 Configuring PHP Sessions
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
