Merge pull request #6926 from kenjis/fix-docs-controllers

docs: improve controller validate()

Author: kenjis

user_guide_src/source/changelogs/v4.2.0.rst

@@ -118,6 +118,7 @@ Commands
 Others
 ======
 
+- Added ``$this->validateData()`` in Controller. See :ref:`controller-validatedata`.
 - Content Security Policy (CSP) enhancements
     - Added the configs ``$scriptNonceTag`` and ``$styleNonceTag`` in  ``Config\ContentSecurityPolicy`` to customize the CSP placeholders (``{csp-script-nonce}`` and ``{csp-style-nonce}``)
     - Added the config ``$autoNonce`` in ``Config\ContentSecurityPolicy`` to disable the CSP placeholder replacement

user_guide_src/source/incoming/controllers.rst

@@ -84,7 +84,7 @@ modify this by passing the duration (in seconds) as the first parameter:
 
 .. _controller-validate:
 
-Validating data
+Validating Data
 ***************
 
 $this->validate()
@@ -95,6 +95,15 @@ The method accepts an array of rules in the first parameter,
 and in the optional second parameter, an array of custom error messages to display
 if the items are not valid. Internally, this uses the controller's
 ``$this->request`` instance to get the data to be validated.
+
+.. warning::
+    The ``validate()`` method uses :ref:`Validation::withRequest() <validation-withrequest>` method.
+    It validates data from :ref:`$request->getJSON() <incomingrequest-getting-json-data>`
+    or :ref:`$request->getRawInput() <incomingrequest-retrieving-raw-data>`
+    or :ref:`$request->getVar() <incomingrequest-getting-data>`.
+    Which data is used depends on the request. Remember that an attacker is free to send any request to
+    the server.
+
 The :doc:`Validation Library docs </libraries/validation>` have details on
 rule and message array formats, as well as available rules:
 
@@ -107,9 +116,13 @@ the ``$rules`` array with the name of the group as defined in **app/Config/Valid
 
 .. note:: Validation can also be handled automatically in the model, but sometimes it's easier to do it in the controller. Where is up to you.
 
+.. _controller-validatedata:
+
 $this->validateData()
 =====================
 
+.. versionadded:: 4.2.0
+
 Sometimes you may want to check the controller method parameters or other custom data.
 In that case, you can use the ``$this->validateData()`` method.
 The method accepts an array of data to validate in the first parameter:

user_guide_src/source/incoming/controllers/006.php

@@ -17,7 +17,9 @@ public function product(int $id)
         ];
 
         if (! $this->validateData($data, $rule)) {
-            // ...
+            return view('store/product', [
+                'errors' => $this->validator->getErrors(),
+            ]);
         }
 
         // ...

user_guide_src/source/incoming/incomingrequest.rst

@@ -80,12 +80,14 @@ With CodeIgniter's built-in methods you can simply do this:
 
 .. literalinclude:: incomingrequest/008.php
 
+.. _incomingrequest-getting-data:
+
 Getting Data
 ============
 
 The ``getVar()`` method will pull from ``$_REQUEST``, so will return any data from ``$_GET``, ``$POST``, or ``$_COOKIE`` (depending on php.ini `request-order <https://www.php.net/manual/en/ini.core.php#ini.request-order>`_).
 
-.. note:: If the incoming request has a ``CONTENT_TYPE`` header set to ``application/json``,
+.. note:: If the incoming request has a ``Content-Type`` header set to ``application/json``,
     the ``getVar()`` method returns the JSON data instead of ``$_REQUEST`` data.
 
 While this
@@ -103,6 +105,8 @@ maintaining the ability to control the order you look for it:
 * ``$request->getPostGet()`` - checks ``$_POST`` first, then ``$_GET``
 * ``$request->getGetPost()`` - checks ``$_GET`` first, then ``$_POST``
 
+.. _incomingrequest-getting-json-data:
+
 Getting JSON Data
 =================
 
@@ -119,7 +123,7 @@ arrays, pass in ``true`` as the first parameter.
 The second and third parameters match up to the ``depth`` and ``options`` arguments of the
 `json_decode <https://www.php.net/manual/en/function.json-decode.php>`_ PHP function.
 
-If the incoming request has a ``CONTENT_TYPE`` header set to ``application/json``, you can also use ``getVar()`` to get
+If the incoming request has a ``Content-Type`` header set to ``application/json``, you can also use ``getVar()`` to get
 the JSON stream. Using ``getVar()`` in this way will always return an object.
 
 Getting Specific Data from JSON
@@ -132,12 +136,14 @@ data that you want or you can use "dot" notation to dig into the JSON to get dat
 
 If you want the result to be an associative array instead of an object, you can use ``getJsonVar()`` instead and pass
 true in the second parameter. This function can also be used if you can't guarantee that the incoming request will have the
-correct ``CONTENT_TYPE`` header.
+correct ``Content-Type`` header.
 
 .. literalinclude:: incomingrequest/011.php
 
 .. note:: See the documentation for :php:func:`dot_array_search()` in the ``Array`` helper for more information on "dot" notation.
 
+.. _incomingrequest-retrieving-raw-data:
+
 Retrieving Raw Data (PUT, PATCH, DELETE)
 ========================================
 

user_guide_src/source/libraries/validation.rst

@@ -276,6 +276,8 @@ To give a labeled error message you can set up as:
 
 .. literalinclude:: validation/007.php
 
+.. _validation-withrequest:
+
 withRequest()
 =============
 
@@ -286,6 +288,15 @@ data to be validated:
 
 .. literalinclude:: validation/008.php
 
+.. note:: This method gets JSON data from
+    :ref:`$request->getJSON() <incomingrequest-getting-json-data>`
+    when the request is a JSON request (``Content-Type: application/json``),
+    or gets Raw data from
+    :ref:`$request->getRawInput() <incomingrequest-retrieving-raw-data>`
+    when the request is a PUT, PATCH, DELETE request and
+    is not HTML form post (``Content-Type: multipart/form-data``),
+    or gets data from :ref:`$request->getVar() <incomingrequest-getting-data>`.
+
 Working with Validation
 ***********************