[Form] Mention that enabling CSRF in forms will start sessions

javiereguiluz · javiereguiluz · commit 036a8a02236c · 2024-07-02T16:09:01.000+02:00
diff --git a/security/csrf.rst b/security/csrf.rst
@@ -72,6 +72,8 @@ protected forms. As an alternative, you can:
   load the CSRF token with an uncached AJAX request and replace the form
   field value with it.
 
+.. _csrf-protection-forms:
+
 CSRF Protection in Symfony Forms
 --------------------------------
 
@@ -82,7 +84,54 @@ protected against CSRF attacks.
 .. _form-csrf-customization:
 
 By default Symfony adds the CSRF token in a hidden field called ``_token``, but
-this can be customized on a form-by-form basis::
+this can be customized (1) globally for all forms and (2) on a form-by-form basis.
+Globally, you can configure it under the ``framework.form`` option:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/framework.yaml
+        framework:
+            # ...
+            form:
+                csrf_protection:
+                    enabled: true
+                    field_name: 'custom_token_name'
+
+    .. 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
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+            <framework:config>
+                <framework:form>
+                    <framework:csrf-protection enabled="true" field-name="custom_token_name"/>
+                </framework:form>
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/framework.php
+        use Symfony\Config\FrameworkConfig;
+
+        return static function (FrameworkConfig $framework) {
+            $framework->form()->csrfProtection()
+                ->enabled(true)
+                ->fieldName('custom_token_name')
+            ;
+        };
+
+On a form-by-form basis, you can configure the CSRF protection in the ``setDefaults()``
+method of each form::
 
     // src/Form/TaskType.php
     namespace App\Form;
diff --git a/session.rst b/session.rst
@@ -110,13 +110,15 @@ By default, session attributes are key-value pairs managed with the
 :class:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBag`
 class.
 
-.. tip::
+Sessions are automatically started whenever you read, write or even check for
+the existence of data in the session. This may hurt your application performance
+because all users will receive a session cookie. In order to prevent starting
+sessions for anonymous users, you must *completely* avoid accessing the session.
+
+.. note::
 
-    Sessions are automatically started whenever you read, write or even check
-    for the existence of data in the session. This may hurt your application
-    performance because all users will receive a session cookie. In order to
-    prevent starting sessions for anonymous users, you must *completely* avoid
-    accessing the session.
+    Sessions will also be created when using features that rely on them internally,
+    such as the :ref:`CSRF protection in forms <csrf-protection-forms>`.
 
 .. _flash-messages:
 
