diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst
index 7e1f0a8a589..782245dab1a 100644
--- a/reference/configuration/framework.rst
+++ b/reference/configuration/framework.rst
@@ -772,18 +772,15 @@ alias will be set to this service id. This class has to implement
handler_id
..........
-**type**: ``string`` **default**: ``'session.handler.native_file'``
-
-The service id used for session storage. The ``session.handler`` service
-alias will be set to this service id.
-
-You can also set it to ``null``, to default to the handler of your PHP
-installation.
+**type**: ``string`` **default**: ``null``
-.. seealso::
+The service id used for session storage. The default ``null`` value means to use
+the native PHP session mechanism. Set it to ``'session.handler.native_file'`` to
+let Symfony manage the sessions itself using files to store the session
+metadata.
- You can see an example of the usage of this in
- :doc:`/doctrine/pdo_session_storage`.
+If you prefer to make Symfony store sessions in a database read
+:doc:`/doctrine/pdo_session_storage`.
.. _name:
diff --git a/session.rst b/session.rst
index 4b4be08a7b0..f6c94439732 100644
--- a/session.rst
+++ b/session.rst
@@ -9,7 +9,7 @@ Configuration
Sessions are provided by the `HttpFoundation component`_, which is included in
all Symfony applications, no matter how you installed it. Before using the
-sessions, check their configuration:
+sessions, check their default configuration:
.. configuration-block::
@@ -20,12 +20,12 @@ sessions, check their configuration:
session:
# enables the support of sessions in the app
enabled: true
-
- # ID of the service used for session storage
- handler_id: session.handler.native_file
-
- # the directory where session metadata is stored
- save_path: '%kernel.project_dir%/var/sessions/%kernel.environment%'
+ # ID of the service used for session storage.
+ # NULL = means that PHP's default session mechanism is used
+ handler_id: null
+ # improves the security of the cookies used for sessions
+ cookie_secure: 'auto'
+ cookie_samesite: 'lax'
.. code-block:: xml
@@ -42,11 +42,13 @@ sessions, check their configuration:
+ handler-id="null"
+ cookie-secure="auto"
+ cookie-samesite="lax" />
@@ -58,15 +60,69 @@ sessions, check their configuration:
// enables the support of sessions in the app
'enabled' => true,
// ID of the service used for session storage
+ // NULL means that PHP's default session mechanism is used
+ 'handler_id' => null,
+ // improves the security of the cookies used for sessions
+ 'cookie_secure' => 'auto',
+ 'cookie_samesite' => 'lax',
+ ],
+ ]);
+
+Setting the ``handler_id`` config option to ``null`` means that Symfony will
+use the native PHP session mechanism. The session metadata files will be stored
+outside of the Symfony application, in a directory controlled by PHP. Although
+this usually simplify things, some session expiration related options may no
+work as expected if other applications that write to the same directory have
+short max lifetime settings.
+
+If you prefer, you can use the ``session.handler.native_file`` service as
+``handler_id`` to let Symfony manage the sessions itself. Another useful option
+is ``save_path``, which defines the directory where Symfony will store the
+session metadata files:
+
+.. configuration-block::
+
+ .. code-block:: yaml
+
+ # config/packages/framework.yaml
+ framework:
+ session:
+ # ...
+ handler_id: 'session.handler.native_file'
+ save_path: '%kernel.project_dir%/var/sessions/%kernel.environment%'
+
+ .. code-block:: xml
+
+
+
+
+
+
+
+
+
+
+ .. code-block:: php
+
+ // config/packages/framework.php
+ $container->loadFromExtension('framework', [
+ 'session' => [
+ // ...
'handler_id' => 'session.handler.native_file',
- // the directory where session metadata is stored
'save_path' => '%kernel.project_dir%/var/sessions/%kernel.environment%',
],
]);
Check out the Symfony config reference to learn more about the other available
:ref:`Session configuration options `. Also, if you
-prefer to store session metadata in the database instead of the filesystem,
+prefer to store session metadata in a database instead of the filesystem,
check out this article: :doc:`/doctrine/pdo_session_storage`.
Basic Usage