Merge branch '4.2'

* 4.2:
  Improved a reference
  Simplified the docs about caching pages with CSRF forms
  Fix words
  Minor rewords in the CSRF docs

Author: javiereguiluz

_build/redirection_map

@@ -401,3 +401,4 @@
 /weblink /web_link
 /components/weblink /components/web_link
 /frontend/encore/installation-no-flex /frontend/encore/installation
+/http_cache/form_csrf_caching /security/csrf

event_dispatcher/before_after_filters.rst

@@ -106,9 +106,9 @@ A controller that implements this interface looks like this::
 Creating an Event Subscriber
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Next, you'll need to create an event listener, which will hold the logic
+Next, you'll need to create an event subscriber, which will hold the logic
 that you want to be executed before your controllers. If you're not familiar with
-event listeners, you can learn more about them at :doc:`/event_dispatcher`::
+event subscribers, you can learn more about them at :doc:`/event_dispatcher`::
 
     // src/EventSubscriber/TokenSubscriber.php
     namespace App\EventSubscriber;

forms.rst

@@ -714,7 +714,7 @@ Learn more
     /form/*
     /controller/upload_file
     /reference/forms/types
-    /http_cache/form_csrf_caching
+    /security/csrf
 
 .. _`Symfony Form component`: https://github.com/symfony/form
 .. _`DateTime`: https://php.net/manual/en/class.datetime.php

http_cache/form_csrf_caching.rst

@@ -65,7 +65,7 @@ at least for some parts of the site, e.g. when using forms with
 :doc:`CSRF Protection </security/csrf>`. In this situation, make sure to
 :doc:`only start a session when actually needed </session/avoid_session_start>`
 and clear the session when it is no longer needed. Alternatively, you can look
-into :doc:`/http_cache/form_csrf_caching`.
+into :ref:`caching pages that contain CSRF protected forms <caching-pages-that-contain-csrf-protected-forms>`.
 
 Cookies created in JavaScript and used only in the frontend, e.g. when using
 Google Analytics, are nonetheless sent to the server. These cookies are not

http_cache/varnish.rst

@@ -138,7 +138,6 @@ Learn more
 ----------
 
 * :doc:`/http_cache/varnish`
-* :doc:`/http_cache/form_csrf_caching`
 
 .. _`byte code caches`: https://en.wikipedia.org/wiki/List_of_PHP_accelerators
 .. _`OPcache`: https://php.net/manual/en/book.opcache.php

performance.rst

@@ -277,6 +277,8 @@ form_rest
 Renders all fields that have not yet been rendered, more information in
 :ref:`the Twig Form reference <reference-forms-twig-rest>`.
 
+.. _reference-twig-function-csrf-token:
+
 csrf_token
 ~~~~~~~~~~
 
@@ -285,10 +287,10 @@ csrf_token
     {{ csrf_token(intention) }}
 
 ``intention``
-    **type**: ``string``
+    **type**: ``string`` - an arbitrary string used to generate the token value.
 
-Renders a CSRF token. Use this function if you want CSRF protection without
-creating a form.
+Renders a CSRF token. Use this function if you want :doc:`CSRF protection </security/csrf>`
+in a regular HTML form not managed by the Symfony Form component.
 
 is_granted
 ~~~~~~~~~~

reference/twig_reference.rst

@@ -55,6 +55,22 @@ for more information):
             'csrf_protection' => null,
         ));
 
+The tokens used for CSRF protection are meant to be different for every user and
+they are stored in the session. That's why a session is started automatically as
+soon as you render a form with CSRF protection.
+
+.. _caching-pages-that-contain-csrf-protected-forms:
+
+Moreover, this means that you cannot fully cache pages that include CSRF
+protected forms. As an alternative, you can:
+
+* Embed the form inside an uncached :doc:`ESI fragment </http_cache/esi>` and
+  cache the rest of the page contents;
+* Cache the entire page and load the form via an uncached AJAX request;
+* Cache the entire page and use :doc:`hinclude.js </templating/hinclude>` to
+  load just the CSRF token with an uncached AJAX request and replace the form
+  field value with it.
+
 CSRF Protection in Symfony Forms
 --------------------------------
 
@@ -92,35 +108,29 @@ this can be customized on a form-by-form basis::
         // ...
     }
 
-.. caution::
-
-    Since the token is stored in the session, a session is started automatically
-    as soon as you render a form with CSRF protection.
-
-.. caution::
-
-    CSRF tokens are meant to be different for every user. Beware of that when
-    caching pages that include forms containing CSRF tokens. For more
-    information, see :doc:`/http_cache/form_csrf_caching`.
-
 CSRF Protection in Login Forms
 ------------------------------
 
 See :doc:`/security/form_login_setup` for a login form that is protected from
 CSRF attacks.
 
-CSRF Protection in HTML Forms
------------------------------
+.. _csrf-protection-in-html-forms:
+
+Generating and Checking CSRF Tokens Manually
+--------------------------------------------
+
+Although Symfony Forms provide automatic CSRF protection by default, you may
+need to generate and check CSRF tokens manually for example when using regular
+HTML forms not managed by the Symfony Form component.
 
-It's also possible to add CSRF protection to regular HTML forms not managed by
-the Symfony Form component, for example the simple forms used to delete items.
-First, use the ``csrf_token()`` function in the Twig template to generate a CSRF
-token and store it as a hidden field of the form:
+Consider a simple HTML form created to allow deleting items. First, use the
+:ref:`csrf_token() Twig function <reference-twig-function-csrf-token>` to
+generate a CSRF token in the template and store it as a hidden form field:
 
 .. code-block:: twig
 
     <form action="{{ url('admin_post_delete', { id: post.id }) }}" method="post">
-        {# the argument of csrf_token() is an arbitrary value used to generate the token #}
+        {# the argument of csrf_token() is an arbitrary string used to generate the token #}
         <input type="hidden" name="token" value="{{ csrf_token('delete-item') }}" />
 
         <button type="submit">Delete item</button>