From 91aa58d2cef29d9210f8d272b1b4eb5c8838a654 Mon Sep 17 00:00:00 2001 From: Ross Motley Date: Mon, 26 Mar 2018 11:16:28 +0100 Subject: [PATCH 1/5] Adding MigratingSessionHandler docs --- .../http_foundation/session_configuration.rst | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/components/http_foundation/session_configuration.rst b/components/http_foundation/session_configuration.rst index 909ac440f22..37bf1227d10 100644 --- 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,35 @@ Example usage:: $sessionStorage = new NativeSessionStorage(array(), new PdoSessionHandler($pdo)); $session = new Session($sessionStorage); +Migrating Between Save Handlers +------------------------------- + +The :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\MigratingSessionHandler` +can be used to migrate between old and new save handlers without losing session data. + +It can be used to support the following 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. +* After your session gc period, verify the data in the new handler +* 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. +* After verifying everything, switch from the migrating handler to the new handler + +Example usage:: + + use Symfony\Component\HttpFoundation\Session\Storage\Handler\MigratingSessionHandler; + + $oldSessionStorage = ...; + $newSessionStorage = ...; + + // First step, for the the garbage collection period so we get all sessions in the new storage handler + $sessionStorage = new MigratingSessionHandler($oldSessionStorage, $newSessionStorage); + + // Second step, just while we verify that the new session storage handler works as expected + $sessionStorage = new MigratingSessionHandler($newSessionStorage, $oldSessionStorage); + + // Final step - switching to the new storage handler! + $sessionStorage = $newSessionStorage; + Configuring PHP Sessions ~~~~~~~~~~~~~~~~~~~~~~~~ From e97107441fbd32dfe682f256c71e689d9396ece9 Mon Sep 17 00:00:00 2001 From: Ross Motley Date: Thu, 17 May 2018 11:21:04 +0100 Subject: [PATCH 2/5] Update session_configuration.rst Added full-stop and tweaked text. --- components/http_foundation/session_configuration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/http_foundation/session_configuration.rst b/components/http_foundation/session_configuration.rst index 37bf1227d10..1fdc4d95b80 100644 --- a/components/http_foundation/session_configuration.rst +++ b/components/http_foundation/session_configuration.rst @@ -99,7 +99,7 @@ It can be used to support the following 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. * After your session gc period, verify the data in the new handler * 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. -* After verifying everything, switch from the migrating handler to the new handler +* After verifying the sessions in your app are working, switch from the migrating handler to the new handler. Example usage:: From 7c8264da3c179c73b1e805844c6e3d7d8d6f3657 Mon Sep 17 00:00:00 2001 From: Ross Motley Date: Thu, 17 May 2018 11:22:11 +0100 Subject: [PATCH 3/5] Update session_configuration.rst Added missing "that". --- components/http_foundation/session_configuration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/http_foundation/session_configuration.rst b/components/http_foundation/session_configuration.rst index 1fdc4d95b80..c81c09de4ce 100644 --- a/components/http_foundation/session_configuration.rst +++ b/components/http_foundation/session_configuration.rst @@ -99,7 +99,7 @@ It can be used to support the following 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. * After your session gc period, verify the data in the new handler * 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. -* After verifying the sessions in your app are working, switch from the migrating handler to the new handler. +* After verifying that the sessions in your app are working, switch from the migrating handler to the new handler. Example usage:: From 386f6393e005f3b7db92c9e17281a2faeb427348 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 22 May 2018 18:06:46 +0200 Subject: [PATCH 4/5] Reworded and simplified --- .../http_foundation/session_configuration.rst | 31 ++++++++----------- 1 file changed, 13 insertions(+), 18 deletions(-) diff --git a/components/http_foundation/session_configuration.rst b/components/http_foundation/session_configuration.rst index c81c09de4ce..0827fa9b5a0 100644 --- a/components/http_foundation/session_configuration.rst +++ b/components/http_foundation/session_configuration.rst @@ -91,30 +91,25 @@ Example usage:: Migrating Between Save Handlers ------------------------------- -The :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\MigratingSessionHandler` -can be used to migrate between old and new save handlers without losing session data. +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. -It can be used to support the following workflow: +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. -* After your session gc period, verify the data in the new handler -* 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. -* After verifying that the sessions in your app are working, switch from the migrating handler to the new handler. +#. 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:: -Example usage:: - - use Symfony\Component\HttpFoundation\Session\Storage\Handler\MigratingSessionHandler; - - $oldSessionStorage = ...; - $newSessionStorage = ...; + $sessionStorage = new MigratingSessionHandler($oldSessionStorage, $newSessionStorage); - // First step, for the the garbage collection period so we get all sessions in the new storage handler - $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:: - // Second step, just while we verify that the new session storage handler works as expected - $sessionStorage = new MigratingSessionHandler($newSessionStorage, $oldSessionStorage); + $sessionStorage = new MigratingSessionHandler($newSessionStorage, $oldSessionStorage); - // Final step - switching to the new storage handler! +#. After verifying that the sessions in your application are working, switch + from the migrating handler to the new handler. $sessionStorage = $newSessionStorage; Configuring PHP Sessions From e93756f975139078fe7363c4279654ae63d6fc3a Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 24 May 2018 10:30:16 +0200 Subject: [PATCH 5/5] Added the versionadded directive --- components/http_foundation/session_configuration.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/components/http_foundation/session_configuration.rst b/components/http_foundation/session_configuration.rst index 0827fa9b5a0..ca4390297be 100644 --- a/components/http_foundation/session_configuration.rst +++ b/components/http_foundation/session_configuration.rst @@ -91,6 +91,9 @@ Example usage:: 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. @@ -110,7 +113,6 @@ This is the recommended migration workflow: #. After verifying that the sessions in your application are working, switch from the migrating handler to the new handler. - $sessionStorage = $newSessionStorage; Configuring PHP Sessions ~~~~~~~~~~~~~~~~~~~~~~~~