Merge pull request #7423 from kenjis/fix-docs-validation.rst

docs: fix validation.rst

Author: kenjis

user_guide_src/source/incoming/controllers.rst

@@ -66,8 +66,6 @@ inside the controller:
 
 .. literalinclude:: controllers/001.php
 
-.. _controllers-validating-data:
-
 forceHTTPS
 **********
 
@@ -84,11 +82,13 @@ modify this by passing the duration (in seconds) as the first parameter:
 
 .. note:: A number of :doc:`time-based constants </general/common_functions>` are always available for you to use, including ``YEAR``, ``MONTH``, and more.
 
-.. _controller-validate:
+.. _controllers-validating-data:
 
 Validating Data
 ***************
 
+.. _controller-validate:
+
 $this->validate()
 =================
 

user_guide_src/source/libraries/validation.rst

@@ -265,8 +265,11 @@ given field, cascading them in order. To set validation rules you
 will use the ``setRule()``, ``setRules()``, or ``withRequest()``
 methods.
 
+Setting a Single Rule
+=====================
+
 setRule()
-=========
+---------
 
 This method sets a single rule. It has the method signature::
 
@@ -285,8 +288,11 @@ the form input name.
     broken in extending classes overriding this method, the child class's method should also be modified
     to remove the typehint.
 
+Setting Multiple Rules
+======================
+
 setRules()
-==========
+----------
 
 Like ``setRule()``, but accepts an array of field names and their rules:
 
@@ -298,6 +304,23 @@ To give a labeled error message you can set up as:
 
 .. _validation-withrequest:
 
+Setting Rules for Array Data
+============================
+
+If your data is in a nested associative array, you can use "dot array syntax" to
+easily validate your data:
+
+.. literalinclude:: validation/009.php
+
+You can use the ``*`` wildcard symbol to match any one level of the array:
+
+.. literalinclude:: validation/010.php
+
+"dot array syntax" can also be useful when you have single dimension array data.
+For example, data returned by multi select dropdown:
+
+.. literalinclude:: validation/011.php
+
 withRequest()
 =============
 
@@ -321,25 +344,37 @@ data to be validated:
 Working with Validation
 ***********************
 
-Validating Keys that are Arrays
-===============================
+Running Validation
+==================
 
-If your data is in a nested associative array, you can use "dot array syntax" to
-easily validate your data:
+The ``run()`` method runs validation. It has the method signature::
 
-.. literalinclude:: validation/009.php
+    run(?array $data = null, ?string $group = null, ?string $dbGroup = null): bool
 
-You can use the '*' wildcard symbol to match any one level of the array:
+The ``$data`` is an array of data to validate. The optional second parameter
+``$group`` is the :ref:`predefined group of rules <validation-array>` to apply.
+The optional third parameter ``$dbGroup`` is the database group to use.
 
-.. literalinclude:: validation/010.php
+This method returns true if the validation is successful.
 
-"dot array syntax" can also be useful when you have single dimension array data.
-For example, data returned by multi select dropdown:
+.. literalinclude:: validation/043.php
 
-.. literalinclude:: validation/011.php
+Running Multiple Validations
+============================
 
-Validate 1 Value
-================
+.. note:: ``run()`` method will not reset error state. Should a previous run fail,
+   ``run()`` will always return false and ``getErrors()`` will return
+   all previous errors until explicitly reset.
+
+If you intend to run multiple validations, for instance on different data sets or with different
+rules after one another, you might need to call ``$validation->reset()`` before each run to get rid of
+errors from previous run. Be aware that ``reset()`` will invalidate any data, rule or custom error
+you previously set, so ``setRules()``, ``setRuleGroup()`` etc. need to be repeated:
+
+.. literalinclude:: validation/019.php
+
+Validating 1 Value
+==================
 
 Validate one value against a rule:
 
@@ -355,7 +390,7 @@ the validation.
 
 .. _validation-array:
 
-How to save your rules
+How to Save Your Rules
 ----------------------
 
 To store your validation rules, simply create a new public property in the ``Config\Validation``
@@ -364,10 +399,16 @@ rules. As shown earlier, the validation array will have this prototype:
 
 .. literalinclude:: validation/013.php
 
+How to Specify Rule Group
+-------------------------
+
 You can specify the group to use when you call the ``run()`` method:
 
 .. literalinclude:: validation/014.php
 
+How to Save Error Messages
+--------------------------
+
 You can also store custom error messages in this configuration file by naming the
 property the same as the group, and appended with ``_errors``. These will automatically
 be used for any errors when this group is used:
@@ -378,7 +419,7 @@ Or pass all settings in an array:
 
 .. literalinclude:: validation/016.php
 
-See below for details on the formatting of the array.
+See :ref:`validation-custom-errors` for details on the formatting of the array.
 
 Getting & Setting Rule Groups
 -----------------------------
@@ -395,20 +436,6 @@ This method sets a rule group from the validation configuration to the validatio
 
 .. literalinclude:: validation/018.php
 
-Running Multiple Validations
-============================
-
-.. note:: ``run()`` method will not reset error state. Should a previous run fail,
-   ``run()`` will always return false and ``getErrors()`` will return
-   all previous errors until explicitly reset.
-
-If you intend to run multiple validations, for instance on different data sets or with different
-rules after one another, you might need to call ``$validation->reset()`` before each run to get rid of
-errors from previous run. Be aware that ``reset()`` will invalidate any data, rule or custom error
-you previously set, so ``setRules()``, ``setRuleGroup()`` etc. need to be repeated:
-
-.. literalinclude:: validation/019.php
-
 Validation Placeholders
 =======================
 

user_guide_src/source/libraries/validation/024.php

@@ -1,20 +1,18 @@
 <?php
 
-$validation->setRules(
-    [
-        'username' => [
-            'label'  => 'Username',
-            'rules'  => 'required|is_unique[users.username]',
-            'errors' => [
-                'required' => 'All accounts must have {field} provided',
-            ],
+$validation->setRules([
+    'username' => [
+        'label'  => 'Username',
+        'rules'  => 'required|is_unique[users.username]',
+        'errors' => [
+            'required' => 'All accounts must have {field} provided',
         ],
-        'password' => [
-            'label'  => 'Password',
-            'rules'  => 'required|min_length[10]',
-            'errors' => [
-                'min_length' => 'Your {field} is too short. You want to get hacked?',
-            ],
+    ],
+    'password' => [
+        'label'  => 'Password',
+        'rules'  => 'required|min_length[10]',
+        'errors' => [
+            'min_length' => 'Your {field} is too short. You want to get hacked?',
         ],
-    ]
-);
+    ],
+]);

user_guide_src/source/libraries/validation/025.php

@@ -1,20 +1,18 @@
 <?php
 
-$validation->setRules(
-    [
-        'username' => [
-            'label'  => 'Rules.username',
-            'rules'  => 'required|is_unique[users.username]',
-            'errors' => [
-                'required' => 'Rules.username.required',
-            ],
+$validation->setRules([
+    'username' => [
+        'label'  => 'Rules.username',
+        'rules'  => 'required|is_unique[users.username]',
+        'errors' => [
+            'required' => 'Rules.username.required',
         ],
-        'password' => [
-            'label'  => 'Rules.password',
-            'rules'  => 'required|min_length[10]',
-            'errors' => [
-                'min_length' => 'Rules.password.min_length',
-            ],
+    ],
+    'password' => [
+        'label'  => 'Rules.password',
+        'rules'  => 'required|min_length[10]',
+        'errors' => [
+            'min_length' => 'Rules.password.min_length',
         ],
-    ]
-);
+    ],
+]);

user_guide_src/source/libraries/validation/036.php

@@ -1,5 +1,5 @@
 <?php
 
-$this->validate($request, [
+$validation->setRules([
     'foo' => 'required|even',
 ]);

user_guide_src/source/libraries/validation/041.php

@@ -1,18 +1,16 @@
 <?php
 
-$validation->setRules(
-    [
-        'foo' => [
-            'required',
-            static function ($value, $data, &$error, $field) {
-                if ((int) $value % 2 === 0) {
-                    return true;
-                }
+$validation->setRules([
+    'foo' => [
+        'required',
+        static function ($value, $data, &$error, $field) {
+            if ((int) $value % 2 === 0) {
+                return true;
+            }
 
-                $error = 'The value is not even.';
+            $error = 'The value is not even.';
 
-                return false;
-            },
-        ],
+            return false;
+        },
     ],
-);
+]);

user_guide_src/source/libraries/validation/043.php

@@ -0,0 +1,9 @@
+<?php
+
+if (! $validation->run($data)) {
+    // handle validation errors
+}
+// or
+if (! $validation->run($data, 'signup')) {
+    // handle validation errors
+}