From 5f415702c99c945a21810f8b36431874897babec Mon Sep 17 00:00:00 2001 From: Drak Date: Sat, 6 Apr 2013 19:50:03 +0100 Subject: [PATCH 1/6] Document start on demand feature. --- .../http_foundation/session_configuration.rst | 37 ++++++++++++++++++- reference/configuration/framework.rst | 4 ++ 2 files changed, 40 insertions(+), 1 deletion(-) diff --git a/components/http_foundation/session_configuration.rst b/components/http_foundation/session_configuration.rst index f445f740b76..df0ab84ed6e 100644 --- a/components/http_foundation/session_configuration.rst +++ b/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:: + + Date: Sat, 6 Apr 2013 20:02:49 +0100 Subject: [PATCH 2/6] Correct markup --- .../http_foundation/session_configuration.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/components/http_foundation/session_configuration.rst b/components/http_foundation/session_configuration.rst index df0ab84ed6e..d92bd8fe300 100644 --- a/components/http_foundation/session_configuration.rst +++ b/components/http_foundation/session_configuration.rst @@ -223,7 +223,7 @@ 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 +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. @@ -231,13 +231,13 @@ There are three modes defined by :class:`Symfony\\Component\\HttpFoundation\\Ses 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 + - ``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 + - ``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:: From e9ee243509f2551ae8fd14835bdd8fa1f6fc917d Mon Sep 17 00:00:00 2001 From: Drak Date: Sat, 6 Apr 2013 22:31:27 +0100 Subject: [PATCH 3/6] Update values. --- reference/configuration/framework.rst | 39 +++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index 3d15cf7cb53..461f0a1bcdf 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -26,6 +26,8 @@ Configuration * enabled * field_name * `session`_ + * `name`_ + * `mock_name`_ * `auto_start`_ * `on_demand`_ * `cookie_lifetime`_ @@ -150,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 ............... From bdc83783e88c5809cffad6dfe3608dced42f4567 Mon Sep 17 00:00:00 2001 From: Drak Date: Sat, 6 Apr 2013 22:32:46 +0100 Subject: [PATCH 4/6] formatting --- components/http_foundation/session_configuration.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/components/http_foundation/session_configuration.rst b/components/http_foundation/session_configuration.rst index d92bd8fe300..9cae338e55a 100644 --- a/components/http_foundation/session_configuration.rst +++ b/components/http_foundation/session_configuration.rst @@ -248,7 +248,9 @@ You can configure these by injecting a configured storage engine into the sessio 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); + $storage = new NativeSessionStorage(array(), + new PdoSessionHandler(), + SessionStorageInterface::NO_START_ON_DEMAND_STRICT); $session = new Session($storage); From 852a205bdcf82c3f3697759469a844ae5caa006a Mon Sep 17 00:00:00 2001 From: Drak Date: Sat, 6 Apr 2013 22:33:34 +0100 Subject: [PATCH 5/6] formatting --- components/http_foundation/session_configuration.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/components/http_foundation/session_configuration.rst b/components/http_foundation/session_configuration.rst index 9cae338e55a..ec542980aed 100644 --- a/components/http_foundation/session_configuration.rst +++ b/components/http_foundation/session_configuration.rst @@ -227,7 +227,8 @@ In versions 2.1-2.2, Symfony Sessions automatically invoked ``$session->start()` 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` +There are three modes defined by +:class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\SessionStorageInterface` The settings are as follows: From 35513bc777f51ea66284b575fd9799d0d2aa9ede Mon Sep 17 00:00:00 2001 From: Drak Date: Thu, 11 Apr 2013 08:52:09 +0100 Subject: [PATCH 6/6] Fix type and clarify behaviour --- components/http_foundation/session_configuration.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/components/http_foundation/session_configuration.rst b/components/http_foundation/session_configuration.rst index ec542980aed..e094ddd0b4f 100644 --- a/components/http_foundation/session_configuration.rst +++ b/components/http_foundation/session_configuration.rst @@ -235,7 +235,8 @@ 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. + when any attempt is made to read or write session data. This setting reflects the default behaviour + since Symfony 2.1 - ``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