8000 Merge branch '4.2' · symfony/symfony-docs@da4fb86 · GitHub
[go: up one dir, main page]
Skip to content

Commit da4fb86

Browse files
javiereguiluzjaviereguiluz
committed
Merge branch '4.2'
* 4.2: Revamped the reference article for Sessions Expanding on repositoryMethod Documented the logout CSRF options Mentioned the LDAP query scopes
2 parents 704f6f6 + ce574b3 commit da4fb86

File tree

11 files changed

+183
-110
lines changed

11 files changed

+183
-110
lines changed

‎_build/redirection_map

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -409,3 +409,5 @@
409409
/profiler/profiling_data /profiler
410410
/profiler/wdt_follow_ajax /profiler
411411
/security/entity_provider /security/user_provider
412+
/session/avoid_session_start /session
413+
/session/sessions_directory /session

‎components/ldap.rst

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,16 @@ array, you may use the
103103

104104
// Do something with the results array
105105

106+
By default, LDAP queries use the ``Symfony\Component\Ldap\Adapter::SCOPE_SUB``
107+
scope, which corresponds to the ``LDAP_SCOPE_SUBTREE`` scope of the
108+
:phpfunction:`ldap_search` function. You can also use ``SCOPE_BASE`` (related
109+
to the ``LDAP_SCOPE_BASE`` scope of :phpfunction:`ldap_read`) and ``SCOPE_ONE``
110+
(related to the ``LDAP_SCOPE_ONELEVEL`` scope of :phpfunction:`ldap_list`)::
111+
112+
use Symfony\Component\Ldap\Adapter;
113+
114+
$query = $ldap->query('dc=symfony,dc=com', '...', ['scope' => Adapter::SCOPE_ONE]);
115+
106116
Creating or Updating Entries
107117
----------------------------
108118

‎controller.rst

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -405,16 +405,13 @@ To get the session, add an argument and type-hint it with
405405

406406
Stored attributes remain in the session for the remainder of that user's session.
407407

408-
.. tip::
409-
410-
Every ``SessionInterface`` implementation is supported. If you have your
411-
own implementation, type-hint this in the argument instead.
412-
413408
For more info, see :doc:`/session`.
414409

415410
.. index::
416411
single: Session; Flash messages
417412

413+
.. _flash-messages:
414+
418415
Flash Messages
419416
~~~~~~~~~~~~~~
420417

‎http_cache/varnish.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ authentication, have Varnish remove the corresponding header from requests to
6363
prevent clients from bypassing the cache. In practice, you will need sessions
6464
at least for some parts of the site, e.g. when using forms with
6565
:doc:`CSRF Protection </security/csrf>`. In this situation, make sure to
66-
:doc:`only start a session when actually needed </session/avoid_session_start>`
66+
:ref:`only start a session when actually needed <session-avoid-start>`
6767
and clear the session when it is no longer needed. Alternatively, you can look
6868
into :ref:`caching pages that contain CSRF protected forms <caching-pages-that-contain-csrf-protected-forms>`.
6969

‎reference/configuration/framework.rst

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -931,7 +931,6 @@ save_path
931931

932932
This determines the argument to be passed to the save handler. If you choose
933933
the default file handler, this is the path where the session files are created.
934-
For more information, see :doc:`/session/sessions_directory`.
935934

936935
You can also set this value to the ``save_path`` of your ``php.ini`` by
937936
setting the value to ``null``:

‎reference/configuration/security.rst

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -181,6 +181,31 @@ success_handler
181181
The service ID used for handling a successful logout. The service must implement
182182
:class:`Symfony\\Component\\Security\\Http\\Logout\\LogoutSuccessHandlerInterface`.
183183

184+
.. _reference-security-logout-csrf:
185+
186+
csrf_parameter
187+
~~~~~~~~~~~~~~
188+
189+
**type**: ``string`` **default**: ``'_csrf_token'``
190+
191+
The name of the parameter that stores the CSRF token value.
192+
193+
csrf_token_generator
194+
~~~~~~~~~~~~~~~~~~~~
195+
196+
**type**: ``string`` **default**: ``null``
197+
198+
The ``id`` of the service used to generate the CSRF tokens. Symfony provides a
199+
default service whose ID is ``security.csrf.token_manager``.
200+
201+
csrf_token_id
202+
~~~~~~~~~~~~~
203+
204+
**type**: ``string`` **default**: ``'logout'``
205+
206+
An arbitrary string used to generate the token value (and check its validity
207+
afterwards).
208+
184209
.. _reference-security-ldap:
185210

186211
LDAP functionality

‎reference/constraints/UniqueEntity.rst

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -169,11 +169,13 @@ not need to be used.
169169
repositoryMethod
170170
~~~~~~~~~~~~~~~~
171171

172-
**type**: ``string`` **default**: ``findBy()``
172+
**type**: ``string`` **default**: ``findBy``
173173

174-
The name of the repository method to use for making the query to determine
175-
the uniqueness. If it's left blank, the ``findBy()`` method will be used.
176-
This method should return a countable result.
174+
The name of the repository method used to determine the uniqueness. If it's left
175+
blank, ``findBy()`` will be used. The method receives as its argument a
176+
``fieldName => value`` associative array (where ``fieldName`` is each of the
177+
fields configured in the ``fields`` option). The method should return a
178+
`countable PHP variable`_.
177179

178180
entityClass
179181
~~~~~~~~~~~
@@ -297,3 +299,4 @@ also has a ``null`` value, validation would fail.
297299
.. include:: /reference/constraints/_payload-option.rst.inc
298300

299301
.. _`race conditions`: https://en.wikipedia.org/wiki/Race_condition
302+
.. _`countable PHP variable`: https://php.net/manual/function.is-countable.php

‎security/csrf.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,8 @@ CSRF Protection in Login Forms
121121
------------------------------
122122

123123
See :doc:`/security/form_login_setup` for a login form that is protected from
124-
CSRF attacks.
124+
CSRF attacks. You can also configure the
125+
:ref:`CSRF protection for the logout action <reference-security-logout-csrf>`.
125126

126127
.. _csrf-protection-in-html-forms:
127128

‎session.rst

Lines changed: 134 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,149 @@
11
Sessions
22
========
33

4-
Symfony provides a nice session object that you can use to store information
5-
about the user between requests.
4+
Symfony provides a session object and several utilities that you can use to
5+
store information about the user between requests.
66

7-
To see how to use the session, read :ref:`session-intro`.
7+
Configuration
8+
-------------
9+
10+
Sessions are provided by the `HttpFoundation component`_, which is included in
11+
all Symfony applications, no matter how you installed it. Before using the
12+
sessions, check their configuration:
13+
14+
.. configuration-block::
15+
16+
.. code-block:: yaml
17+
18+
# config/packages/framework.yaml
19+
framework:
20+
session:
21+
# enables the support of sessions in the app
22+
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%'
29+
30+
.. code-block:: xml
31+
32+
<!-- config/packages/framework.xml -->
33+
<?xml version="1.0" encoding="UTF-8" ?>
34+
<container xmlns="http://symfony.com/schema/dic/services"
35+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
36+
xmlns:framework="http://symfony.com/schema/dic/symfony"
37+
xsi:schemaLocation="http://symfony.com/schema/dic/services
38+
http://symfony.com/schema/dic/services/services-1.0.xsd
39+
http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
40+
41+
<framework:config>
42+
<!--
43+
enabled: enables the support of sessions in the app
44+
handler-id: ID of the service used for session storage
45+
save_path: the directory where session metadata is stored
46+
-->
47+
<framework:session enabled="true"
48+
handler-id="session.handler.native_file"
49+
save-path="%kernel.project_dir%/var/sessions/%kernel.environment%" />
50+
</framework:config>
51+
</container>
52+
53+
.. code-block:: php
54+
55+
// config/packages/framework.php
56+
$container->loadFromExtension('framework', [
57+
'session' => [
58+
// enables the support of sessions in the app
59+
'enabled' => true,
60+
// ID of the service used for session storage
61+
'handler_id' => 'session.handler.native_file',
62+
// the directory where session metadata is stored
63+
'save_path' => '%kernel.project_dir%/var/sessions/%kernel.environment%',
64+
],
65+
]);
66+
67+
Check out the Symfony config reference to learn more about the other available
68+
:ref:`Session configuration options <config-framework-session>`. Also, if you
69+
prefer to store session metadata in the database instead of the filesystem,
70+
check out this article: :doc:`/doctrine/pdo_session_storage`.
71+
72+
Basic Usage
73+
-----------
74+
75+
Symfony provides a session service that is injected in your services and
76+
controllers if you type-hint an argument with
77+
:class:`Symfony\\Component\\HttpFoundation\\Session\\SessionInterface`::
78+
79+
use Symfony\Component\HttpFoundation\Session\SessionInterface;
80+
81+
class SomeService
82+
{
83+
private $session;
84+
85+
public function __construct(SessionInterface $session)
86+
{
87+
$this->session = $session;
88+
}
89+
90+
public function someMethod()
91+
{
92+
// stores an attribute in the session for later reuse
93+
$session->set('attribute-name', 'attribute-value');
94+
95+
// gets an attribute by name
96+
$foo = $session->get('foo');
97+
98+
// uses a default value if the attribute doesn't exist
99+
$filters = $session->get('filters', []);
100+
101+
// ...
102+
}
103+
}
104+
105+
Stored attributes remain in the session for the remainder of that user's session.
106+
107+
.. tip::
108+
109+
Every ``SessionInterface`` implementation is supported. If you have your
110+
own implementation, type-hint this in the argument instead.
111+
112+
.. _session-avoid-start:
113+
114+
Avoid Starting Sessions for Anonymous Users
115+
-------------------------------------------
116+
117+
Sessions are automatically started whenever you read, write or even check for
118+
the existence of data in the session. This may hurt your application performance
119+
because all users will receive a session cookie. In order to prevent that, you
120+
must *completely* avoid accessing the session.
121+
122+
For example, if your templates include some code to display the
123+
:ref:`flash messages <flash-messages>`, sessions will start even if the user
124+
is not logged in and even if you haven't created any flash messages. To avoid
125+
this behavior, add a check before trying to access the flash messages:
126+
127+
.. code-block:: html+twig
128+
129+
{# this check prevents starting a session when there are no flash messages #}
130+
{% if app.request.hasPreviousSession %}
131+
{% for message in app.flashes('notice') %}
132+
<div class="flash-notice">
133+
{{ message }}
134+
</div>
135+
{% endfor %}
136+
{% endif %}
8137

9138
More about Sessions
10139
-------------------
11140

12141
.. toctree::
13142
:maxdepth: 1
14143

15-
session/sessions_directory
16-
session/avoid_session_start
144+
/doctrine/pdo_session_storage
17145
session/locale_sticky_session
18146
session/php_bridge
19147
session/proxy_examples
20148

21-
* :doc:`/doctrine/pdo_session_storage`
149+
.. _`HttpFoundation component`: https://symfony.com/components/HttpFoundation

‎session/avoid_session_start.rst

Lines changed: 0 additions & 38 deletions
This file was deleted.

‎session/sessions_directory.rst

Lines changed: 0 additions & 54 deletions
This file was deleted.

0 commit comments

Comments
 (0)
0