symfony · javiereguiluz · Jan 14, 2019 · Jan 14, 2019
diff --git a/_build/redirection_map b/_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
diff --git a/forms.rst b/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

diff --git a/http_cache/form_csrf_caching.rst b/http_cache/form_csrf_caching.rst
diff --git a/http_cache/varnish.rst b/http_cache/varnish.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 :doc:`/security/csrf`.
 
 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

diff --git a/performance.rst b/performance.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

diff --git a/security/csrf.rst b/security/csrf.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,17 +108,6 @@ 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
 ------------------------------
 
@@ -113,6 +118,7 @@ CSRF Protection in HTML Forms
 -----------------------------
 
 .. versionadded:: 4.1
+
     In Symfony versions prior to 4.1, CSRF support required installing the
     Symfony Form component even if you didn't use it.