Merge branch '5.4' into 6.2

* 5.4:
  fix link to psr7 bridge classes
  [Process] 📝 process: `create_new_console` is only for windows
  Adding section "Configuring Garbage Collection"

Author: javiereguiluz

components/process.rst

@@ -109,6 +109,11 @@ You can configure the options passed to the ``other_options`` argument of
     // this option allows a subprocess to continue running after the main script exited
     $process->setOptions(['create_new_console' => true]);
 
+.. note::
+
+    The ``create_new_console`` option is only available on Windows!
+
+
 Using Features From the OS Shell
 --------------------------------
 

components/psr7.rst

@@ -29,9 +29,9 @@ Usage
 Converting from HttpFoundation Objects to PSR-7
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The bridge provides an interface of a factory called
-:class:`Symfony\\Bridge\\PsrHttpMessage\\HttpMessageFactoryInterface`
-that builds objects implementing PSR-7 interfaces from HttpFoundation objects.
+The bridge provides an interface of a factory called 
+`HttpMessageFactoryInterface`_ that builds objects implementing PSR-7
+interfaces from HttpFoundation objects.
 
 The following code snippet explains how to convert a :class:`Symfony\\Component\\HttpFoundation\\Request`
 to a ``Nyholm\Psr7\ServerRequest`` class implementing the
@@ -66,8 +66,8 @@ Converting Objects implementing PSR-7 Interfaces to HttpFoundation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 On the other hand, the bridge provide a factory interface called
-:class:`Symfony\\Bridge\\PsrHttpMessage\\HttpFoundationFactoryInterface`
-that builds HttpFoundation objects from objects implementing PSR-7 interfaces.
+`HttpFoundationFactoryInterface`_ that builds HttpFoundation objects from
+objects implementing PSR-7 interfaces.
 
 The next snippet explain how to convert an object implementing the
 ``Psr\Http\Message\ServerRequestInterface`` interface to a
@@ -93,3 +93,5 @@ to a :class:`Symfony\\Component\\HttpFoundation\\Response` instance::
 .. _`PSR-7`: https://www.php-fig.org/psr/psr-7/
 .. _`PSR-17`: https://www.php-fig.org/psr/psr-17/
 .. _`libraries that implement psr/http-factory-implementation`: https://packagist.org/providers/psr/http-factory-implementation
+.. _`HttpMessageFactoryInterface`: https://github.com/symfony/psr-http-message-bridge/blob/main/HttpMessageFactoryInterface.php
+.. _`HttpFoundationFactoryInterface`: https://github.com/symfony/psr-http-message-bridge/blob/main/HttpFoundationFactoryInterface.php

session.rst

@@ -409,7 +409,7 @@ logged in by destroying the session after a certain period of idle time. For
 example, it is common for banking applications to log the user out after just
 5 to 10 minutes of inactivity. Setting the cookie lifetime here is not
 appropriate because that can be manipulated by the client, so we must do the expiry
-on the server side. The easiest way is to implement this via garbage collection
+on the server side. The easiest way is to implement this via :ref:`session garbage collection <session-garbage-collection>`
 which runs reasonably frequently. The ``cookie_lifetime`` would be set to a
 relatively high value, and the garbage collection ``gc_maxlifetime`` would be set
 to destroy sessions at whatever the desired idle period is.
@@ -443,6 +443,42 @@ 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-garbage-collection:
+
+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/packages/framework.yaml
+    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