From d840fef9236056ebc8734941e973a55924185bcc Mon Sep 17 00:00:00 2001
From: kenjis <kenji.uui@gmail.com>
Date: Wed, 13 Sep 2023 11:11:40 +0900
Subject: [PATCH] docs: add and update docs

---
 .../installation/upgrade_validations.rst      | 13 +++---
 .../source/libraries/validation.rst           | 23 ++++++++++
 .../source/libraries/validation/046.php       | 43 +++++++++++++++++++
 .../source/libraries/validation/047.php       | 22 ++++++++++
 4 files changed, 96 insertions(+), 5 deletions(-)
 create mode 100644 user_guide_src/source/libraries/validation/046.php
 create mode 100644 user_guide_src/source/libraries/validation/047.php

diff --git a/user_guide_src/source/installation/upgrade_validations.rst b/user_guide_src/source/installation/upgrade_validations.rst
index 8343b989a699..b45823716869 100644
--- a/user_guide_src/source/installation/upgrade_validations.rst
+++ b/user_guide_src/source/installation/upgrade_validations.rst
@@ -14,12 +14,15 @@ Documentations of Library
 What has been changed
 =====================
 - If you want to change validation error display, you have to set CI4 :ref:`validation View templates <validation-customizing-error-display>`.
-- CI4 validation has no Callbacks nor Callable in CI3.
-  Use :ref:`Rule Classes <validation-using-rule-classes>` or
-  :ref:`Closure Rule <validation-using-closure-rule>`
-  instead.
-- In CI3, Callbacks/Callable rules were prioritized, but in CI4, Closure Rules are
+- CI4 validation has no `Callbacks <http://www.codeigniter.com/userguide3/libraries/form_validation.html#callbacks-your-own-validation-methods>`_
+  in CI3.
+  Use :ref:`Callable Rules <validation-using-callable-rule>` (since v4.5.0) or
+  :ref:`Closure Rules <validation-using-closure-rule>` (since v4.3.0) or
+  :ref:`Rule Classes <validation-using-rule-classes>` instead.
+- In CI3, Callbacks/Callable rules were prioritized, but in CI4, Closure/Callable Rules are
   not prioritized, and are checked in the order in which they are listed.
+- Since v4.5.0, :ref:`Callable Rules <validation-using-callable-rule>` has been
+  introduced, but it is a bit different from CI3's `Callable <http://www.codeigniter.com/userguide3/libraries/form_validation.html#callable-use-anything-as-a-rule>`_.
 - CI4 validation format rules do not permit empty string.
 - CI4 validation never changes your data.
 - Since v4.3.0, :php:func:`validation_errors()` has been introduced, but the API is different from CI3's.
diff --git a/user_guide_src/source/libraries/validation.rst b/user_guide_src/source/libraries/validation.rst
index 3224961e0821..2f3cdd662d70 100644
--- a/user_guide_src/source/libraries/validation.rst
+++ b/user_guide_src/source/libraries/validation.rst
@@ -794,6 +794,29 @@ Or you can use the following parameters:
 .. literalinclude:: validation/041.php
    :lines: 2-
 
+.. _validation-using-callable-rule:
+
+Using Callable Rule
+===================
+
+.. versionadded:: 4.5.0
+
+If you like to use an array callback as a rule, you may use it instead of a Closure Rule.
+
+You need to use an array for validation rules:
+
+.. literalinclude:: validation/046.php
+   :lines: 2-
+
+You must set the error message for the callable rule.
+When you specify the error message, set the array key for the callable rule.
+In the above code, the ``required`` rule has the key ``0``, and the callable has ``1``.
+
+Or you can use the following parameters:
+
+.. literalinclude:: validation/047.php
+   :lines: 2-
+
 ***************
 Available Rules
 ***************
diff --git a/user_guide_src/source/libraries/validation/046.php b/user_guide_src/source/libraries/validation/046.php
new file mode 100644
index 000000000000..f37def009eba
--- /dev/null
+++ b/user_guide_src/source/libraries/validation/046.php
@@ -0,0 +1,43 @@
+<?php
+
+namespace App\Controllers;
+
+use Config\Services;
+
+class Form extends BaseController
+{
+    // Define a custom validation rule.
+    public function _ruleEven($value): bool
+    {
+        return (int) $value % 2 === 0;
+    }
+
+    public function process()
+    {
+        // ...
+
+        $validation = Services::validation();
+        $validation->setRules(
+            [
+                'foo' => [
+                    'required',
+                    // Specify the method in this controller as a rule.
+                    [$this, '_ruleEven'],
+                ],
+            ],
+            [
+                // Errors
+                'foo' => [
+                    // Specify the array key for the callable rule.
+                    1 => 'The value is not even.',
+                ],
+            ],
+        );
+
+        if (! $validation->run($data)) {
+            // handle validation errors
+        }
+
+        // ...
+    }
+}
diff --git a/user_guide_src/source/libraries/validation/047.php b/user_guide_src/source/libraries/validation/047.php
new file mode 100644
index 000000000000..6c2bb674f800
--- /dev/null
+++ b/user_guide_src/source/libraries/validation/047.php
@@ -0,0 +1,22 @@
+<?php
+
+namespace App\Controllers;
+
+use Config\Services;
+
+class Form extends BaseController
+{
+    // Define a custom validation rule.
+    public function _ruleEven($value, $data, &$error, $field): bool
+    {
+        if ((int) $value % 2 === 0) {
+            return true;
+        }
+
+        $error = 'The value is not even.';
+
+        return false;
+    }
+
+    // ...
+}