8000 More improvements of the Session article by javiereguiluz · Pull Request #11033 · symfony/symfony-docs · GitHub
[go: up one dir, main page]
Skip to content

More improvements of the Session article #11033

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 22, 2019
Merged

More improvements of the Session article #11033

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 7 additions & 10 deletions reference/configuration/framework.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
80 changes: 68 additions & 12 deletions 8000 session.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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::

Expand All @@ -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

Expand All @@ -42,11 +42,13 @@ sessions, check their configuration:
<!--
enabled: enables the support of sessions in the app
handler-id: ID of the service used for session storage
save_path: the directory where session metadata is stored
NULL means that PHP's default session mechanism is used
cookie-secure and cookie-samesite: improves the security of the cookies used for sessions
-->
<framework:session enabled="true"
handler-id="session.handler.native_file"
save-path="%kernel.project_dir%/var/sessions/%kernel.environment%" />
handler-id="null"
cookie-secure="auto"
cookie-samesite="lax" />
</framework:config>
</container>

Expand All @@ -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

<!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

<framework:config>
<framework:session enabled="true"
handler-id="session.handler.native_file"
save-path="%kernel.project_dir%/var/sessions/%kernel.environment%" />
</framework:config>
</container>

.. 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 <config-framework-session>`. 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
Expand Down
0