diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index c4196b0b035..d98207e594d 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -148,6 +148,7 @@ * :doc:`/cookbook/session/locale_sticky_session` * :doc:`/cookbook/session/sessions_directory` * :doc:`/cookbook/session/php_bridge` + * :doc:`/cookbook/session/limit_metadata_writes` * **symfony1** diff --git a/cookbook/session/index.rst b/cookbook/session/index.rst index 536ad02c3d8..dede3362434 100644 --- a/cookbook/session/index.rst +++ b/cookbook/session/index.rst @@ -7,4 +7,5 @@ Sessions proxy_examples locale_sticky_session sessions_directory - php_bridge \ No newline at end of file + php_bridge + limit_metadata_writes diff --git a/cookbook/session/limit_metadata_writes.rst b/cookbook/session/limit_metadata_writes.rst new file mode 100644 index 00000000000..b2d0208d21c --- /dev/null +++ b/cookbook/session/limit_metadata_writes.rst @@ -0,0 +1,68 @@ +.. index:: + single: Limit Metadata Writes; Session + +Limit session metadata writes +============================= + +.. versionadded:: 2.4 + The ability to limit session metadata writes was added in Symfony 2.4. + +The default behaviour of PHP session is to persist the session regardless of +whether the session data has changed or not. In Symfony, each time the session +is accessed metadata is recorded (session created/last used) which can be used +to determine session age and idle time. + +If for performance reasons you wish to limit the frequency at which the session +persists, this feature can adjust the granularity of the metadata updates and +persist the session less often while still maintaining relatively accurate +metadata. If other session data is changed, the session will always persist. + +You can tell Symfony not to update the metadata "session last updated" time +until a certain amount of time has passed, by setting +``framework.session.metadata_update_threshold`` to a value in seconds greater +than zero: + +.. configuration-block:: + + .. code-block:: yaml + + framework: + session: + metadata_update_threshold: 120 + + .. code-block:: xml + + + + + + + + + + + .. code-block:: php + + $container->loadFromExtension('framework', array( + 'session' => array( + 'metadata_update_threshold' => 120, + ), + )); + +.. info:: + + PHP default's behavior is to save the session whether it has been changed or + not. When using ``framework.session.metadata_update_threshold`` Symfony + will wrap the session handler (configured at + ``framework.session.handler_id``) into the WriteCheckSessionHandler, that + will prevent any session write if the session was not modified. + +.. caution:: + + Be aware that if the session is not written at every request, it may be + garbage collected sooner than usual. This means that your users may be + logged out sooner than expected.