[WCM] Document PhpSessionStorage

components/http_foundation/index.rst

@@ -8,4 +8,5 @@ HTTP Foundation
     sessions
     session_configuration
     session_testing
+    session_php_bridge
     trusting_proxies

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::
+
+    <?php
+    use Symfony\Component\HttpFoundation\Session\Session;
+    use Symfony\Component\HttpFoundation\Session\Storage\PhpBridgeSessionStorage;
+
+    // legacy application configures session
+    ini_set('session.save_handler', 'files');
+    ini_set('session.save_path', '/tmp');
+    session_start();
+
+    // Get Symfony to interface with this existing session
+    $session = new Session(new PhpBridgeSessionStorage());
+
+    // symfony will now interface with the existing PHP session
+    $session->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.
+

cookbook/index.rst

@@ -25,6 +25,7 @@ The Cookbook
     debugging
     event_dispatcher/index
     request/index
+    session/index
     profiler/index
     web_services/index
     symfony1

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`

cookbook/sessions/index.rst

@@ -0,0 +1,7 @@
+Sessions
+========
+
+.. toctree::
+    :maxdepth: 2
+
+    php_bridge

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
+