Adding section "Configuring Garbage Collection"

session.rst

@@ -446,6 +446,39 @@ particular cookie by reading the ``getLifetime()`` method::
 The expiry time of the cookie can be determined by adding the created
 timestamp and the lifetime.
 
+Configuring Garbage Collection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When a session opens, PHP will call the ``gc`` handler randomly according to the
+probability set by ``session.gc_probability`` / ``session.gc_divisor``. For
+example if these were set to ``5/100`` respectively, it would mean a probability
+of 5%. Similarly, ``3/4`` would mean a 3 in 4 chance of being called, i.e. 75%.
+
+If the garbage collection handler is invoked, PHP will pass the value stored in
+the ``php.ini`` directive ``session.gc_maxlifetime``. The meaning in this context is
+that any stored session that was saved more than ``gc_maxlifetime`` ago should be
+deleted. This allows one to expire records based on idle time.
+
+However, some operating systems (e.g. Debian) do their own session handling and set
+the ``session.gc_probability`` variable to ``0`` to stop PHP doing garbage
+collection. That's why Symfony now overwrites this value to ``1``.
+
+If you wish to use the original value set in your ``php.ini``, add the following
+configuration:
+
+.. code-block:: yaml
+
+    # config.yml
+    framework:
+        session:
+            gc_probability: null
+
+You can configure these settings by passing ``gc_probability``, ``gc_divisor``
+and ``gc_maxlifetime`` in an array to the constructor of
+:class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\NativeSessionStorage`
+or to the :method:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\NativeSessionStorage::setOptions`
+method.
+
 .. _session-database:
 
 Store Sessions in a Database