diff --git a/components/http_foundation/index.rst b/components/http_foundation/index.rst index 9937c960776..348f8e50ca4 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_bridge trusting_proxies diff --git a/components/http_foundation/session_php_bridge.rst b/components/http_foundation/session_php_bridge.rst new file mode 100644 index 00000000000..ae636f26213 --- /dev/null +++ b/components/http_foundation/session_php_bridge.rst @@ -0,0 +1,49 @@ +.. 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\\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``. + +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. + +.. 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. + 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 +