From 5921a7b8783a5c3d99af90ed5a10d5f8f77ea07e Mon Sep 17 00:00:00 2001 From: Drak Date: Sat, 6 Apr 2013 18:59:10 +0100 Subject: [PATCH 1/6] Document PhpSessionStorage --- .../http_foundation/session_php_legacy.rst | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 components/http_foundation/session_php_legacy.rst diff --git a/components/http_foundation/session_php_legacy.rst b/components/http_foundation/session_php_legacy.rst new file mode 100644 index 00000000000..2cb19c7d2be --- /dev/null +++ b/components/http_foundation/session_php_legacy.rst @@ -0,0 +1,40 @@ +.. index:: + single: HTTP + single: HttpFoundation, Sessions + +Integrating with legacy sessions +================================ + +Sometimes it may be necessary to integrate Symfony into a legacy application +where you do not initially have the level of control you require. + +As stated elsewhere, Symfony Sessions are designed to replace the use of +PHP's native `session_*()` functions and use of the `$_SESSION` +superglobal. Additionally, it is mandatory for Symfony to start the session. + +However when there really are circumstances where this is not possible, it is possible +to use a special storage bridge +:class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\PhpSessionStorage` +which is designed to allow Symfony to work with a session started outside of +the Symfony Session framework. You are warned that things can interrupt this +use case unless you are careful: for example legacy application erases `$_SESSION`. + +Typical use of this might look as follows:: + + start(); + +This will allow you to start using the Symfony Session API and allow +migration of your application to Symfony Sessions. \ No newline at end of file From 043773381c07b7be0879c87cff8c0c24cc5a0fb4 Mon Sep 17 00:00:00 2001 From: Drak Date: Sat, 6 Apr 2013 19:13:33 +0100 Subject: [PATCH 2/6] Update index --- components/http_foundation/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/components/http_foundation/index.rst b/components/http_foundation/index.rst index 9937c960776..c638e784903 100644 --- a/components/http_foundation/index.rst +++ b/components/http_foundation/index.rst @@ -8,4 +8,5 @@ HTTP Foundation sessions session_configuration session_testing + session_php_legacy trusting_proxies From 67a5ecde4ba541f82a222cd64bcf1a1a6629433e Mon Sep 17 00:00:00 2001 From: Drak Date: Sat, 6 Apr 2013 20:08:35 +0100 Subject: [PATCH 3/6] Added nortes as per @stof's recommendation. --- components/http_foundation/session_php_legacy.rst | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/components/http_foundation/session_php_legacy.rst b/components/http_foundation/session_php_legacy.rst index 2cb19c7d2be..1950785ab53 100644 --- a/components/http_foundation/session_php_legacy.rst +++ b/components/http_foundation/session_php_legacy.rst @@ -9,7 +9,7 @@ Sometimes it may be necessary to integrate Symfony into a legacy application where you do not initially have the level of control you require. As stated elsewhere, Symfony Sessions are designed to replace the use of -PHP's native `session_*()` functions and use of the `$_SESSION` +PHP's native ``session_*()`` functions and use of the ``$_SESSION`` superglobal. Additionally, it is mandatory for Symfony to start the session. However when there really are circumstances where this is not possible, it is possible @@ -17,7 +17,7 @@ to use a special storage bridge :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\PhpSessionStorage` which is designed to allow Symfony to work with a session started outside of the Symfony Session framework. You are warned that things can interrupt this -use case unless you are careful: for example legacy application erases `$_SESSION`. +use case unless you are careful: for example legacy application erases ``$_SESSION``. Typical use of this might look as follows:: @@ -37,4 +37,13 @@ Typical use of this might look as follows:: $session->start(); This will allow you to start using the Symfony Session API and allow -migration of your application to Symfony Sessions. \ No newline at end of file +migration of your application to Symfony Sessions. + +.. note:: + +Symfony Sessions store data like attributes in special 'Bags' which use a +key in the ``$_SESSION`` superglobal. This means that a Symfony Session +cannot access arbitary keys in ``$_SESSION`` that may be set by the legacy +application, although all the ``$_SESSION`` contents will be saved when +the session is saved. + From 793e5703ebf000353ee04bbb5f486bb3b18ddd6c Mon Sep 17 00:00:00 2001 From: Drak Date: Sat, 6 Apr 2013 22:20:21 +0100 Subject: [PATCH 4/6] Style fixes --- components/http_foundation/session_php_legacy.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/components/http_foundation/session_php_legacy.rst b/components/http_foundation/session_php_legacy.rst index 1950785ab53..69903ef7b0b 100644 --- a/components/http_foundation/session_php_legacy.rst +++ b/components/http_foundation/session_php_legacy.rst @@ -2,7 +2,7 @@ single: HTTP single: HttpFoundation, Sessions -Integrating with legacy sessions +Integrating with Legacy Sessions ================================ Sometimes it may be necessary to integrate Symfony into a legacy application @@ -41,9 +41,9 @@ migration of your application to Symfony Sessions. .. note:: -Symfony Sessions store data like attributes in special 'Bags' which use a -key in the ``$_SESSION`` superglobal. This means that a Symfony Session -cannot access arbitary keys in ``$_SESSION`` that may be set by the legacy -application, although all the ``$_SESSION`` contents will be saved when -the session is saved. + Symfony Sessions store data like attributes in special 'Bags' which use a + key in the ``$_SESSION`` superglobal. This means that a Symfony Session + cannot access arbitary keys in ``$_SESSION`` that may be set by the legacy + application, although all the ``$_SESSION`` contents will be saved when + the session is saved. From 39c66cedc1e2f690a60fe2a87b52f6b2d57f7dfb Mon Sep 17 00:00:00 2001 From: Drak Date: Sat, 13 Apr 2013 19:26:47 +0100 Subject: [PATCH 5/6] Sync with PR class name change. --- components/http_foundation/index.rst | 2 +- .../{session_php_legacy.rst => session_php_bridge.rst} | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) rename components/http_foundation/{session_php_legacy.rst => session_php_bridge.rst} (91%) diff --git a/components/http_foundation/index.rst b/components/http_foundation/index.rst index c638e784903..348f8e50ca4 100644 --- a/components/http_foundation/index.rst +++ b/components/http_foundation/index.rst @@ -8,5 +8,5 @@ HTTP Foundation sessions session_configuration session_testing - session_php_legacy + session_php_bridge trusting_proxies diff --git a/components/http_foundation/session_php_legacy.rst b/components/http_foundation/session_php_bridge.rst similarity index 91% rename from components/http_foundation/session_php_legacy.rst rename to components/http_foundation/session_php_bridge.rst index 69903ef7b0b..ae636f26213 100644 --- a/components/http_foundation/session_php_legacy.rst +++ b/components/http_foundation/session_php_bridge.rst @@ -14,7 +14,7 @@ superglobal. Additionally, it is mandatory for Symfony to start the session. However when there really are circumstances where this is not possible, it is possible to use a special storage bridge -:class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\PhpSessionStorage` +:class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\PhpBridgeSessionStorage` which is designed to allow Symfony to work with a session started outside of the Symfony Session framework. You are warned that things can interrupt this use case unless you are careful: for example legacy application erases ``$_SESSION``. @@ -23,7 +23,7 @@ Typical use of this might look as follows:: start(); From ae777064b12e27255171442ddb92e5571fe4d2fa Mon Sep 17 00:00:00 2001 From: Drak Date: Sat, 13 Apr 2013 19:41:51 +0100 Subject: [PATCH 6/6] Add cookbook entry. --- cookbook/index.rst | 1 + cookbook/map.rst.inc | 4 ++++ cookbook/sessions/index.rst | 7 +++++++ cookbook/sessions/php_bridge.rst | 36 ++++++++++++++++++++++++++++++++ 4 files changed, 48 insertions(+) create mode 100644 cookbook/sessions/index.rst create mode 100644 cookbook/sessions/php_bridge.rst diff --git a/cookbook/index.rst b/cookbook/index.rst index 8131c58898a..d50b4b025fa 100644 --- a/cookbook/index.rst +++ b/cookbook/index.rst @@ -25,6 +25,7 @@ The Cookbook debugging event_dispatcher/index request/index + session/index profiler/index web_services/index symfony1 diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index 67e3684fb81..a6af2450860 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -102,6 +102,10 @@ * :doc:`/cookbook/request/mime_type` +* :doc:`/cookbook/session/index` + + * :doc:`/cookbook/session/php_bridge` + * :doc:`/cookbook/routing/index` * :doc:`/cookbook/routing/scheme` diff --git a/cookbook/sessions/index.rst b/cookbook/sessions/index.rst new file mode 100644 index 00000000000..e7550bb723c --- /dev/null +++ b/cookbook/sessions/index.rst @@ -0,0 +1,7 @@ +Sessions +======== + +.. toctree:: + :maxdepth: 2 + + php_bridge diff --git a/cookbook/sessions/php_bridge.rst b/cookbook/sessions/php_bridge.rst new file mode 100644 index 00000000000..2021baf707e --- /dev/null +++ b/cookbook/sessions/php_bridge.rst @@ -0,0 +1,36 @@ +.. index:: + single: Sessions + +Bridge a legacy application with Symfony Sessions +-------------------------------------------------------- + +.. versionadded:: 2.3 +Added ability to integrate with a legacy PHP session + +You may take advantage of the PHP Bridge Session when integrating +a legacy application into the Symfony Full Stack Framework when it +may not be possible to avoid the legacy application starting the +session with ``session_start()`` + +If the application has sets it's own PHP save handler, you can +specify null for the ``handler_id``: + +.. code-block:: yml + + framework: + session: + storage_id: session.storage.php_bridge + handler_id: ~ + +Otherwise, if the problem is simply that you cannot avoid the application +starting the session with ``session_start()`` but you can still make use of +a Symfony based session save handler, you can specify the save handle +as in the example below: + +.. code-block:: yml + + framework: + session: + storage_id: session.storage.php_bridge + handler_id: session.handler.native_file +