Document start on demand feature.

components/http_foundation/session_configuration.rst

@@ -79,7 +79,7 @@ examples if you wish to write your own.
 Example usage::
 
     use Symfony\Component\HttpFoundation\Session\Session;
-    use Symfony\Component\HttpFoundation\Session\Storage\SessionStorage;
+    use Symfony\Component\HttpFoundation\Session\Storage\NativeSessionStorage;
     use Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler;
 
     $storage = new NativeSessionStorage(array(), new PdoSessionHandler());
@@ -217,6 +217,44 @@ particular cookie by reading the ``getLifetime()`` method::
 The expiry time of the cookie can be determined by adding the created
 timestamp and the lifetime.
 
+Session start-on-demand
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 2.3
+  Control over session "start-on-demand" was added in Symfony 2.3.
+
+In versions 2.1-2.2, Symfony Sessions automatically invoked ``$session->start()`` when
+any attempt was made to access session data (effectively 'start on demand').
+From Symfony 2.3 this behaviour can be controlled.
+
+There are three modes defined by
+:class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\SessionStorageInterface`
+
+The settings are as follows:
+
+  - ``SessionStorageInterface::NO_START_ON_DEMAND_STRICT`` - The session will not be started on demand
+    and any attempt to read or write session data will result in a ``\RuntimeException``
+  - ``SessionStorageInterface::START_ON_DEMAND`` - The session will be started if it hasn't already been
+    when any attempt is made to read ro write session data.
+  - ``SessionStorageInterface::NO_START_ON_DEMAND_LAX`` - The sessions will not be started on demand
+    when session data is read or written to. It will allow access to the unitialized ``BagInterface``.
+    If this session is subsequently started manually after data is written to a ``BagInterface`` will
+    be overwritten (by the session data read from persistence).
+
+You can configure these by injecting a configured storage engine into the session::
+
+    <?php
+    use Symfony\Component\HttpFoundation\Session\Session;
+    use Symfony\Component\HttpFoundation\Session\Storage\NativeSessionStorage;
+    use Symfony\Component\HttpFoundation\Session\Storage\SessionStorageInterface;
+    use Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler;
+
+    $storage = new NativeSessionStorage(array(),
+                                        new PdoSessionHandler(),
+                                        SessionStorageInterface::NO_START_ON_DEMAND_STRICT);
+    $session = new Session($storage);
+
+
 PHP 5.4 compatibility
 ~~~~~~~~~~~~~~~~~~~~~
 

reference/configuration/framework.rst

@@ -26,6 +26,10 @@ Configuration
     * enabled
     * field_name
 * `session`_
+    * `name`_
+    * `mock_name`_
+    * `auto_start`_
+    * `on_demand`_
     * `cookie_lifetime`_
     * `cookie_path`_
     * `cookie_domain`_
@@ -148,6 +152,43 @@ csrf_protection
 session
 ~~~~~~~
 
+on_demand
+.........
+
+**type**:  ``string`` **default**: ``on``
+
+Can be values
+
+  - ``on`` - start automatically if not started upon session read/write
+  - ``off`` - do not start session automatically on data read/write, if an attempt is
+    make to do so, throw a ``\RuntimeException``
+  - ``off_lax`` - do not start session automatically on data read/write, but if an attempt
+    is made to read or write to the session, allow access to the relevent bag.
+    If data is written to the bags and a session is subsequently started, it will be
+    overwritten.
+
+auto_start
+..........
+
+**type**:  ``Boolean`` **default**: ``false``
+
+This controls the ``SessionListener`` which will automatically start the session
+during the Request cycle.
+
+name
+....
+
+**type**:  ``string``
+
+Sets the session cookie name
+
+mock_name
+.........
+
+**type**:  ``string``
+
+Sets the mock session cookie name
+
 cookie_lifetime
 ...............
 
@@ -462,6 +503,8 @@ Full Default Configuration
             session:
                 storage_id:           session.storage.native
                 handler_id:           session.handler.native_file
+                auto_start:           false
+                on_demand:            on #on, off or off_lax
                 name:                 ~
                 cookie_lifetime:      ~
                 cookie_path:          ~