Merge pull request #6951 from kenjis/feat-closure-validation-rule

feat: add closure validation rule

Author: kenjis

system/Validation/Validation.php

@@ -11,6 +11,7 @@
 
 namespace CodeIgniter\Validation;
 
+use Closure;
 use CodeIgniter\HTTP\IncomingRequest;
 use CodeIgniter\HTTP\RequestInterface;
 use CodeIgniter\Validation\Exceptions\ValidationException;
@@ -195,7 +196,7 @@ public function check($value, string $rule, array $errors = []): bool
      *
      * @param array|string $value
      * @param array|null   $rules
-     * @param array        $data          The array of data to validate, with `DBGroup`.
+     * @param array|null   $data          The array of data to validate, with `DBGroup`.
      * @param string|null  $originalField The original asterisk field name like "foo.*.bar".
      */
     protected function processRules(
@@ -277,7 +278,7 @@ protected function processRules(
             $rules = array_diff($rules, ['permit_empty']);
         }
 
-        foreach ($rules as $rule) {
+        foreach ($rules as $i => $rule) {
             $isCallable = is_callable($rule);
 
             $passed = false;
@@ -292,7 +293,9 @@ protected function processRules(
             $error = null;
 
             // If it's a callable, call and get out of here.
-            if ($isCallable) {
+            if ($this->isClosure($rule)) {
+                $passed = $rule($value, $data, $error, $field);
+            } elseif ($isCallable) {
                 $passed = $param === false ? $rule($value) : $rule($value, $param, $data);
             } else {
                 $found = false;
@@ -333,7 +336,7 @@ protected function processRules(
 
                 // @phpstan-ignore-next-line $error may be set by rule methods.
                 $this->errors[$field] = $error ?? $this->getErrorMessage(
-                    $rule,
+                    $this->isClosure($rule) ? $i : $rule,
                     $field,
                     $label,
                     $param,
@@ -348,6 +351,14 @@ protected function processRules(
         return true;
     }
 
+    /**
+     * @param Closure|string $rule
+     */
+    private function isClosure($rule): bool
+    {
+        return $rule instanceof Closure;
+    }
+
     /**
      * Is the array a string list `list<string>`?
      */

tests/system/Validation/ValidationTest.php

@@ -204,6 +204,81 @@ public function testRunDoesTheBasics(): void
         $this->assertFalse($this->validation->run($data));
     }
 
+    public function testClosureRule(): void
+    {
+        $this->validation->setRules(
+            [
+                'foo' => ['required', static fn ($value) => $value === 'abc'],
+            ],
+            [
+                // Errors
+                'foo' => [
+                    // Specify the array key for the closure rule.
+                    1 => 'The value is not "abc"',
+                ],
+            ],
+        );
+
+        $data   = ['foo' => 'xyz'];
+        $return = $this->validation->run($data);
+
+        $this->assertFalse($return);
+        $this->assertSame(
+            ['foo' => 'The value is not "abc"'],
+            $this->validation->getErrors()
+        );
+    }
+
+    public function testClosureRuleWithParamError(): void
+    {
+        $this->validation->setRules([
+            'foo' => [
+                'required',
+                static function ($value, $data, &$error, $field) {
+                    if ($value !== 'abc') {
+                        $error = 'The ' . $field . ' value is not "abc"';
+
+                        return false;
+                    }
+
+                    return true;
+                },
+            ],
+        ]);
+
+        $data   = ['foo' => 'xyz'];
+        $return = $this->validation->run($data);
+
+        $this->assertFalse($return);
+        $this->assertSame(
+            ['foo' => 'The foo value is not "abc"'],
+            $this->validation->getErrors()
+        );
+    }
+
+    public function testClosureRuleWithLabel(): void
+    {
+        $this->validation->setRules([
+            'secret' => [
+                'label'  => 'シークレット',
+                'rules'  => ['required', static fn ($value) => $value === 'abc'],
+                'errors' => [
+                    // Specify the array key for the closure rule.
+                    1 => 'The {field} is invalid',
+                ],
+            ],
+        ]);
+
+        $data   = ['secret' => 'xyz'];
+        $return = $this->validation->run($data);
+
+        $this->assertFalse($return);
+        $this->assertSame(
+            ['secret' => 'The シークレット is invalid'],
+            $this->validation->getErrors()
+        );
+    }
+
     /**
      * @see https://github.com/codeigniter4/CodeIgniter4/issues/5368
      *

user_guide_src/source/changelogs/v4.3.0.rst

@@ -307,6 +307,7 @@ Others
 - **Routing:** Added new ``$routes->view()`` method to return the view directly. See :ref:`View Routes <view-routes>`.
 - **View:** View Cells are now first-class citizens and can be located in the **app/Cells** directory. See :ref:`View Cells <app-cells>`.
 - **View:** Added ``Controlled Cells`` that provide more structure and flexibility to your View Cells. See :ref:`View Cells <controlled-cells>` for details.
+- **Validation:** Added Closure validation rule. See :ref:`validation-using-closure-rule` for details.
 - **Config:** Now you can specify Composer packages to auto-discover manually. See :ref:`Code Modules <modules-specify-composer-packages>`.
 - **Debug:** Kint has been updated to 5.0.1.
 - **Request:** Added new ``$request->getRawInputVar()`` method to return a specified variable from raw stream. See :ref:`Retrieving Raw data <incomingrequest-retrieving-raw-data>`.

user_guide_src/source/libraries/validation.rst

@@ -579,15 +579,26 @@ right after the name of the field the error should belong to::
 Creating Custom Rules
 *********************
 
+Using Rule Classes
+==================
+
 Rules are stored within simple, namespaced classes. They can be stored any location you would like, as long as the
-autoloader can find it. These files are called RuleSets. To add a new RuleSet, edit **Config/Validation.php** and
+autoloader can find it. These files are called RuleSets.
+
+Adding a RuleSet
+----------------
+
+To add a new RuleSet, edit **Config/Validation.php** and
 add the new file to the ``$ruleSets`` array:
 
 .. literalinclude:: validation/033.php
 
 You can add it as either a simple string with the fully qualified class name, or using the ``::class`` suffix as
 shown above. The primary benefit here is that it provides some extra navigation capabilities in more advanced IDEs.
 
+Creating a Rule Class
+---------------------
+
 Within the file itself, each method is a rule and must accept a string as the first parameter, and must return
 a boolean true or false value signifying true if it passed the test or false if it did not:
 
@@ -599,12 +610,15 @@ second parameter:
 
 .. literalinclude:: validation/035.php
 
+Using a Custom Rule
+-------------------
+
 Your new custom rule could now be used just like any other rule:
 
 .. literalinclude:: validation/036.php
 
 Allowing Parameters
-===================
+-------------------
 
 If your method needs to work with parameters, the function will need a minimum of three parameters: the string to validate,
 the parameter string, and an array with all of the data that was submitted the form. The ``$data`` array is especially handy
@@ -614,6 +628,28 @@ for rules like ``required_with`` that needs to check the value of another submit
 
 Custom errors can be returned as the fourth parameter, just as described above.
 
+.. _validation-using-closure-rule:
+
+Using Closure Rule
+==================
+
+.. versionadded:: 4.3.0
+
+If you only need the functionality of a custom rule once throughout your application,
+you may use a closure instead of a rule class.
+
+You need to use an array for validation rules:
+
+.. literalinclude:: validation/040.php
+
+You must set the error message for the closure rule.
+When you specify the error message, set the array key for the closure rule.
+In the above code, the ``required`` rule has the key ``0``, and the closure has ``1``.
+
+Or you can use the following parameters:
+
+.. literalinclude:: validation/041.php
+
 Available Rules
 ***************
 

user_guide_src/source/libraries/validation/003.php

@@ -4,7 +4,9 @@
 
 class Validation
 {
-    public $ruleSets = [
+    // ...
+
+    public array $ruleSets = [
         \CodeIgniter\Validation\CreditCardRules::class,
         \CodeIgniter\Validation\FileRules::class,
         \CodeIgniter\Validation\FormatRules::class,

user_guide_src/source/libraries/validation/033.php

@@ -9,7 +9,9 @@
 
 class Validation
 {
-    public $ruleSets = [
+    // ...
+
+    public array $ruleSets = [
         Rules::class,
         FormatRules::class,
         FileRules::class,

user_guide_src/source/libraries/validation/040.php

@@ -0,0 +1,21 @@
+<?php
+
+$validation->setRules(
+    [
+        'foo' => [
+            'required',
+            static fn ($value) => (int) $value % 2 === 0,
+        ],
+    ],
+    [
+        // Errors
+        'foo' => [
+            // Specify the array key for the closure rule.
+            1 => 'The value is not even.',
+        ],
+    ],
+);
+
+if (! $validation->run($data)) {
+    // handle validation errors
+}

user_guide_src/source/libraries/validation/041.php

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