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