10000 minor #11033 More improvements of the Session article (javiereguiluz) · symfony/symfony-docs@f01458b · GitHub
[go: up one dir, main page]
Skip to content

Commit f01458b

Browse files
javiereguiluzjaviereguiluz
committed
minor #11033 More improvements of the Session article (javiereguiluz)
This PR was merged into the 4.2 branch. Discussion ---------- More improvements of the Session article This continues #11027. We now use by default the initial session config created by the recipe: https://github.com/symfony/recipes/blob/master/symfony/framework-bundle/4.2/config/packages/framework.yaml#L10 We also explain things better to fix #8498. Commits ------- d02ff77 More improvements of the Session article
2 parents 12544a4 + d02ff77 commit f01458b

File tree

2 files changed

+75
-22
lines changed

2 files changed

+75
-22
lines changed

‎reference/configuration/framework.rst

Lines changed: 7 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -790,18 +790,15 @@ alias will be set to this service id. This class has to implement
790790
handler_id
791791
..........
792792

793-
**type**: ``string`` **default**: ``'session.handler.native_file'``
794-
795-
The service id used for session storage. The ``session.handler`` service
796-
alias will be set to this service id.
797-
798-
You can also set it to ``null``, to default to the handler of your PHP
799-
installation.
793+
**type**: ``string`` **default**: ``null``
800794

801-
.. seealso::
795+
The service id used for session storage. The default ``null`` value means to use
796+
the native PHP session mechanism. Set it to ``'session.handler.native_file'`` to
797+
let Symfony manage the sessions itself using files to store the session
798+
metadata.
802799

803-
You can see an example of the usage of this in
804-
:doc:`/doctrine/pdo_session_storage`.
800+
If you prefer to make Symfony store sessions in a database read
801+
:doc:`/doctrine/pdo_session_storage`.
805802

806803
.. _name:
807804

‎session.rst

Lines changed: 68 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Configuration
99

1010
Sessions are provided by the `HttpFoundation component`_, which is included in
1111
all Symfony applications, no matter how you installed it. Before using the
12-
sessions, check their configuration:
12+
sessions, check their default configuration:
1313

1414
.. configuration-block::
1515

@@ -20,12 +20,12 @@ sessions, check their configuration:
2020
session:
2121
# enables the support of sessions in the app
2222
enabled: true
23-
24-
# ID of the service used for session storage
25-
handler_id: session.handler.native_file
26-
27-
# the directory where session metadata is stored
28-
save_path: '%kernel.project_dir%/var/sessions/%kernel.environment%'
23+
# ID of the service used for session storage.
24+
# NULL = means that PHP's default session mechanism is used
25+
handler_id: null
26+
# improves the security of the cookies used for sessions
27+
cookie_secure: 'auto'
28+
cookie_samesite: 'lax'
2929
3030
.. code-block:: xml
3131
@@ -42,11 +42,13 @@ sessions, check their configuration:
4242
<!--
4343
enabled: enables the support of sessions in the app
4444
handler-id: ID of the service used for session storage
45-
save_path: the directory where session metadata is stored
45+
NULL means that PHP's default session mechanism is used
46+
cookie-secure and cookie-samesite: improves the security of the cookies used for sessions
4647
-->
4748
<framework:session enabled="true"
48-
handler-id="session.handler.native_file"
49-
save-path="%kernel.project_dir%/var/sessions/%kernel.environment%" />
49+
handler-id="null"
50+
cookie-secure="auto"
51+
cookie-samesite="lax" />
5052
</framework:config>
5153
</container>
5254
@@ -58,15 +60,69 @@ sessions, check their configuration:
5860
// enables the support of sessions in the app
5961
'enabled' => true,
6062
// ID of the service used for session storage
63+
// NULL means that PHP's default session mechanism is used
64+
'handler_id' => null,
65+
// improves the security of the cookies used for sessions
66+
'cookie_secure' => 'auto',
67+
'cookie_samesite' => 'lax',
68+
],
69+
]);
70+
71+
Setting the ``handler_id`` config option to ``null`` means that Symfony will
72+
use the native PHP session mechanism. The session metadata files will be stored
73+
outside of the Symfony application, in a directory controlled by PHP. Although
74+
this usually simplify things, some session expiration related options may no
75+
work as expected if other applications that write to the same directory have
76+
short max lifetime settings.
77+
78+
If you prefer, you can use the ``session.handler.native_file`` service as
79+
``handler_id`` to let Symfony manage the sessions itself. Another useful option
80+
is ``save_path``, which defines the directory where Symfony will store the
81+
session metadata files:
82+
83+
.. configuration-block::
84+
85+
.. code-block:: yaml
86+
87+
# config/packages/framework.yaml
88+
framework:
89+
session:
90+
# ...
91+
handler_id: 'session.handler.native_file'
92+
save_path: '%kernel.project_dir%/var/sessions/%kernel.environment%'
93+
94+
.. code-block:: xml
95+
96+
<!-- config/packages/framework.xml -->
97+
<?xml version="1.0" encoding="UTF-8" ?>
98+
<container xmlns="http://symfony.com/schema/dic/services"
99+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
100+
xmlns:framework="http://symfony.com/schema/dic/symfony"
101+
xsi:schemaLocation="http://symfony.com/schema/dic/services
102+
http://symfony.com/schema/dic/services/services-1.0.xsd
103+
http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
104+
105+
<framework:config>
106+
<framework:session enabled="true"
107+
handler-id="session.handler.native_file"
108+
save-path="%kernel.project_dir%/var/sessions/%kernel.environment%" />
109+
</framework:config>
110+
</container>
111+
112+
.. code-block:: php
113+
114+
// config/packages/framework.php
115+
$container->loadFromExtension('framework', [
116+
'session' => [
117+
// ...
61118
'handler_id' => 'session.handler.native_file',
62-
// the directory where session metadata is stored
63119
'save_path' => '%kernel.project_dir%/var/sessions/%kernel.environment%',
64120
],
65121
]);
66122
67123
Check out the Symfony config reference to learn more about the other available
68124
:ref:`Session configuration options <config-framework-session>`. Also, if you
69-
prefer to store session metadata in the database instead of the filesystem,
125+
prefer to store session metadata in a database instead of the filesystem,
70126
check out this article: :doc:`/doctrine/pdo_session_storage`.
71127

72128
Basic Usage

0 commit comments

Comments
 (0)
0