Merge pull request #8935 from obozdag/patch-12

docs: fix helpers/form_helper.rst

Author: kenjis

user_guide_src/source/helpers/form_helper.rst

@@ -28,7 +28,7 @@ Escaping Field Values
 *********************
 
 You may need to use HTML and characters such as quotes within your form
-elements. In order to do that safely, you'll need to use
+elements. In order to do that safely, you'll need to use the
 :doc:`common function <../general/common_functions>`
 :php:func:`esc()`.
 
@@ -64,8 +64,8 @@ The following functions are available:
 
     Creates an opening form tag with a site URL **built from your** ``Config\App::$baseURL``.
     It will optionally let you add form attributes and hidden input fields, and
-    will always add the `accept-charset` attribute based on the charset value in your
-    config file.
+    will always add the `accept-charset` attribute based on the ``$charset`` property in your
+    **app/Config/App.php** config file.
 
     The main benefit of using this tag rather than hard coding your own HTML is that
     it permits your site to be more portable in the event your URLs ever change.
@@ -103,16 +103,21 @@ The following functions are available:
 
             <form action="http://example.com/index.php/email/send" class="email" id="myform" method="post" accept-charset="utf-8">
 
-        If :ref:`CSRF <cross-site-request-forgery>` filter is turned on ``form_open()`` will generate CSRF field at the beginning of the form. You can specify ID of this field by passing csrf_id as one of the ``$attribute`` array:
+        If :ref:`CSRF <cross-site-request-forgery>` filter is turned on ``form_open()`` will generate CSRF field at the beginning of the form. You can specify ID of this field by passing **csrf_id** as an element of the ``$attributes`` array:
 
         .. literalinclude:: form_helper/007.php
 
         will return::
 
             <form action="http://example.com/index.php/u/sign-up" method="post" accept-charset="utf-8">
-            <input type="hidden" id="my-id" name="csrf_field" value="964ede6e0ae8a680f7b8eab69136717d">
+            <input type="hidden" id="my-id" name="csrf_test_name" value="964ede6e0ae8a680f7b8eab69136717d">
 
-        .. note:: To use auto-generation of CSRF field, you need to turn CSRF filter on to the form page. In most cases it is requested using the ``GET`` method.
+        .. note:: To use auto-generation of CSRF field, you need to turn on the :ref:`CSRF filter <enable-csrf-protection>` in **app/Config/Filters.php** file.
+            In most cases the form page is requested using the GET method. Normally, CSRF protection is required
+            for POST/PUT/DELETE/PATCH requests, but even for GET requests, CSRF filters must be enabled for pages that display Forms.
+            
+            If you enable CSRF filter with :ref:`filters-globals`, it will be active for all request types.
+            But if you enable CSRF filter with ``public array $methods = ['POST' => ['csrf']];``, the hidden CSRF field will not be added in GET requests.
 
     **Adding Hidden Input Fields**
 
@@ -145,7 +150,7 @@ The following functions are available:
 
     :param    string    $name: Field name
     :param    string    $value: Field value
-    :returns:    An HTML hidden input field tag
+    :returns:    An HTML hidden input element
     :rtype:    string
 
     Lets you generate hidden input fields. You can either submit a
@@ -171,7 +176,7 @@ The following functions are available:
     :param    string    $value: Field value
     :param    mixed    $extra: Extra attributes to be added to the tag either as an array or a literal string
     :param  string  $type: The type of input field. i.e., 'text', 'email', 'number', etc.
-    :returns:    An HTML text input field tag
+    :returns:    An HTML text input element
     :rtype:    string
 
     Lets you generate a standard text input field. You can minimally pass
@@ -206,7 +211,7 @@ The following functions are available:
     :param    array    $data: Field attributes data
     :param    string    $value: Field value
     :param    mixed    $extra: Extra attributes to be added to the tag either as an array or a literal string
-    :returns:    An HTML password input field tag
+    :returns:    An HTML password input element
     :rtype:    string
 
     This function is identical in all respects to the :php:func:`form_input()`
@@ -217,7 +222,7 @@ The following functions are available:
     :param    array    $data: Field attributes data
     :param    string    $value: Field value
     :param    mixed    $extra: Extra attributes to be added to the tag either as an array or a literal string
-    :returns:    An HTML file upload input field tag
+    :returns:    An HTML file upload input element
     :rtype:    string
 
     This function is identical in all respects to the :php:func:`form_input()`
@@ -229,7 +234,7 @@ The following functions are available:
     :param    array    $data: Field attributes data
     :param    string    $value: Field value
     :param    mixed    $extra: Extra attributes to be added to the tag either as an array or a literal string
-    :returns:    An HTML textarea tag
+    :returns:    An HTML textarea element
     :rtype:    string
 
     This function is identical in all respects to the :php:func:`form_input()`
@@ -244,7 +249,7 @@ The following functions are available:
     :param    array    $options: An associative array of options to be listed
     :param    array    $selected: List of fields to mark with the *selected* attribute
     :param    mixed    $extra: Extra attributes to be added to the tag either as an array or a literal string
-    :returns:    An HTML dropdown select field tag
+    :returns:    An HTML select (dropdown) element
     :rtype:    string
 
     Lets you create a standard drop-down field. The first parameter will
@@ -278,7 +283,7 @@ The following functions are available:
     :param    array    $options: An associative array of options to be listed
     :param    array    $selected: List of fields to mark with the *selected* attribute
     :param    mixed    $extra: Extra attributes to be added to the tag either as an array or a literal string
-    :returns:    An HTML dropdown multiselect field tag
+    :returns:    An HTML select element with multiple attribute
     :rtype:    string
 
     Lets you create a standard multiselect field. The first parameter will
@@ -326,7 +331,7 @@ The following functions are available:
     :param    string    $value: Field value
     :param    bool    $checked: Whether to mark the checkbox as being *checked*
     :param    mixed    $extra: Extra attributes to be added to the tag either as an array or a literal string
-    :returns:    An HTML checkbox input tag
+    :returns:    An HTML checkbox input element
     :rtype:    string
 
     Lets you generate a checkbox field. Simple example:
@@ -357,7 +362,7 @@ The following functions are available:
     :param    string    $value: Field value
     :param    bool    $checked: Whether to mark the radio button as being *checked*
     :param    mixed    $extra: Extra attributes to be added to the tag either as an array or a literal string
-    :returns:    An HTML radio input tag
+    :returns:    An HTML radio input element
     :rtype:    string
 
     This function is identical in all respects to the :php:func:`form_checkbox()`
@@ -368,7 +373,7 @@ The following functions are available:
     :param    string    $label_text: Text to put in the <label> tag
     :param    string    $id: ID of the form element that we're making a label for
     :param    string    $attributes: HTML attributes
-    :returns:    An HTML field label tag
+    :returns:    An HTML label element
     :rtype:    string
 
     Lets you generate a <label>. Simple example:
@@ -387,7 +392,7 @@ The following functions are available:
     :param    string    $data: Button name
     :param    string    $value: Button value
     :param    mixed    $extra: Extra attributes to be added to the tag either as an array or a literal string
-    :returns:    An HTML input submit tag
+    :returns:    An HTML input submit element
     :rtype:    string
 
     Lets you generate a standard submit button. Simple example:
@@ -403,7 +408,7 @@ The following functions are available:
     :param    string    $data: Button name
     :param    string    $value: Button value
     :param    mixed    $extra: Extra attributes to be added to the tag either as an array or a literal string
-    :returns:    An HTML input reset button tag
+    :returns:    An HTML input reset element
     :rtype:    string
 
     Lets you generate a standard reset button. Use is identical to
@@ -414,7 +419,7 @@ The following functions are available:
     :param    string    $data: Button name
     :param    string    $content: Button label
     :param    mixed    $extra: Extra attributes to be added to the tag either as an array or a literal string
-    :returns:    An HTML button tag
+    :returns:    An HTML button element
     :rtype:    string
 
     Lets you generate a standard button element. You can minimally pass the
@@ -452,10 +457,10 @@ The following functions are available:
     :returns:    Field value
     :rtype:    string
 
-    Permits you to set the value of an input form or textarea. You must
+    Permits you to set the value of an input or textarea element. You must
     supply the field name via the first parameter of the function. The
     second (optional) parameter allows you to set a default value for the
-    form. The third (optional) parameter allows you to turn off HTML escaping
+    field value. The third (optional) parameter allows you to turn off HTML escaping
     of the value, in case you need to use this function in combination with
     i.e., :php:func:`form_input()` and avoid double-escaping.
 

user_guide_src/source/incoming/filters.rst

@@ -139,6 +139,8 @@ Filters can be specified by adding their alias to either the ``before`` or ``aft
 
 .. literalinclude:: filters/013.php
 
+.. _filters-globals:
+
 $globals
 --------
 

user_guide_src/source/libraries/security.rst

@@ -152,6 +152,8 @@ This provides a nicer experience than simply crashing.
 
 Even when the redirect value is ``true``, AJAX calls will not redirect, but will throw a SecurityException.
 
+.. _enable-csrf-protection:
+
 Enable CSRF Protection
 ======================