Document start on demand feature.

Author: Drak

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,41 @@ 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,8 @@ Configuration
     * enabled
     * field_name
 * `session`_
+    * `auto_start`_
+    * `on_demand`_
     * `cookie_lifetime`_
     * `cookie_path`_
     * `cookie_domain`_
@@ -462,6 +464,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:          ~