feat: [Validation] add required_if rule

system/Language/en/Validation.php

@@ -53,6 +53,7 @@
     'required'              => 'The {field} field is required.',
     'required_with'         => 'The {field} field is required when {param} is present.',
     'required_without'      => 'The {field} field is required when {param} is not present.',
+    'required_if'           => 'The {field} field is required when the {param} field has the given value.',
     'string'                => 'The {field} field must be a valid string.',
     'timezone'              => 'The {field} field must be a valid timezone.',
     'valid_base64'          => 'The {field} field must be a valid base64 string.',

system/Validation/Rules.php

@@ -436,6 +436,47 @@ public function required_without(
         return true;
     }
 
+    /**
+     * This field is required when any of the other required fields have their expected values present
+     * in the data.
+     *
+     * Example (The special_option field is required when the normal_option,1,2 field has the given value.):
+     *
+     *     required_if[normal_option,1,2]
+     *
+     * @param string|null          $str
+     * @param string|null          $fieldWithValue that we should check if present
+     * @param array<string, mixed> $data           Complete list of field from the form
+     */
+    public function required_if($str = null, ?string $fieldWithValue = null, array $data = []): bool
+    {
+        if ($fieldWithValue === null || $data === []) {
+            throw new InvalidArgumentException('You must supply the parameters: field,expected_values, data.');
+        }
+
+        // Separate fields and expected values
+        $parts          = explode(',', $fieldWithValue);
+        $field          = array_shift($parts); // Get field
+        $expectedValues = $parts; // The remainder is the expected value
+
+        if (trim($field) === '' || $expectedValues === []) {
+            throw new InvalidArgumentException('You must supply the expected values of field: E.g. field,value1,value2,...');
+        }
+
+        // If the field does not exist in the data, immediately return true
+        if (! array_key_exists($field, $data)) {
+            return true;
+        }
+
+        // If the value of a field matches one of the expected values, then this field is required
+        if (in_array($data[$field], $expectedValues, true)) {
+            // The field to be checked must exist and cannot be empty
+            return trim($str ?? '') !== '';
+        }
+
+        return true;
+    }
+
     /**
      * The field exists in $data.
      *

system/Validation/StrictRules/Rules.php

@@ -407,6 +407,23 @@ public function required_without(
         return $this->nonStrictRules->required_without($str, $otherFields, $data, $error, $field);
     }
 
+    /**
+     * This field is required when any of the other required fields have their expected values present
+     * in the data.
+     *
+     * Example (The special_option field is required when the normal_option,1,2 field has the given value.):
+     *
+     *     required_if[normal_option,1,2]
+     *
+     * @param string|null          $str
+     * @param string|null          $fieldWithValue that we should check if present
+     * @param array<string, mixed> $data           Complete list of field from the form
+     */
+    public function required_if($str = null, ?string $fieldWithValue = null, array $data = []): bool
+    {
+        return $this->nonStrictRules->required_if($str, $fieldWithValue, $data);
+    }
+
     /**
      * The field exists in $data.
      *

system/Validation/Validation.php

@@ -436,7 +436,7 @@ private function processPermitEmpty($value, array $rules, array $data)
                         $rule  = $match[1];
                         $param = $match[2];
 
-                        if (! in_array($rule, ['required_with', 'required_without'], true)) {
+                        if (! in_array($rule, ['required_with', 'required_without', 'required_if'], true)) {
                             continue;
                         }
 

tests/system/Validation/RulesTest.php

@@ -923,4 +923,65 @@
             $this->validation->getErrors()
         );
     }
+
+    /**
+     * @param array<string, mixed> $data
+     */
+    #[DataProvider('provideRequiredIf')]
+    public function testRequiredIf(bool $expected, array $data): void
+    {
+        $this->validation->setRules([
+            'special_option' => 'required_if[normal_option,1,2]',
+        ]);
+
+        $result = $this->validation->run($data);
+
+        $this->assertSame($expected, $result);
+    }
+
+    public static function provideRequiredIf(): iterable
+    {
+        yield from [
+            // `normal_option` and `special_option` do not exist
+            [true, []],
+            // `special_option` is not required because `normal_option` field does not have expected value
+            [true, ['normal_option' => '', 'special_option' => '']],
+            [true, ['normal_option' => '0', 'special_option' => '']],
+            [true, ['normal_option' => null, 'special_option' => '']],
+            // `special_option` is required and exist
+            [false, ['normal_option' => '1', 'special_option' => '']],
+            [false, ['normal_option' => '2', 'special_option' => '']],
+            // `special_option` is required but do not exist
+            [false, ['normal_option' => '1']],
+            [false, ['normal_option' => '2']],
+        ];
+    }
+
+    /**
+     * @param array<string, mixed> $data
+     */
+    #[DataProvider('provideRequiredIfWorkWithOtherRule')]
+    public function testRequiredIfWorkWithOtherRule(bool $expected, array $data): void
+    {
+        $this->validation->setRules([
+            'special_option' => 'required_if[normal_option,1,2]|permit_empty|integer',
+        ]);
+
+        $result = $this->validation->run($data);
+
+        $this->assertSame($expected, $result);
+    }
+
+    public static function provideRequiredIfWorkWithOtherRule(): iterable
+    {
+        yield from [
+            // `special_option` with integer value
+            [true, ['normal_option' => '1', 'special_option' => '1']],
+            [true, ['normal_option' => '2', 'special_option' => '1']],
+            // `special_option` is not empty, but it is not an integer
+            // value, which triggers the Validation.integer error message.
+            [false, ['normal_option' => '1', 'special_option' => 'a']],
+            [false, ['normal_option' => '2', 'special_option' => 'b']],
+        ];
+    }
 }

user_guide_src/source/changelogs/v4.6.0.rst

@@ -146,8 +146,9 @@ Libraries
 
 - **FileCollection:** Added ``retainMultiplePatterns()`` to ``FileCollection`` class.
   See :ref:`FileCollection::retainMultiplePatterns() <file-collections-retain-multiple-patterns>`.
-- **Validation:** Added ``min_dims`` validation rule to ``FileRules`` class. See
-  :ref:`Validation <rules-for-file-uploads>`.
+- **Validation:** 
+    - Added ``min_dims`` validation rule to ``FileRules`` class. See :ref:`Validation <rules-for-file-uploads>`.
+    - Added ``required_if`` validation rule to ``Rules`` class. See :ref:`Validation <rules-for-general-use>`.
 
 Helpers and Functions
 =====================
@@ -165,6 +166,7 @@ Message Changes
 ***************
 
 - Added ``Validation.min_dims`` message
+- Added ``Validation.required_if`` message
 
 *******
 Changes

user_guide_src/source/libraries/validation.rst

@@ -972,10 +972,13 @@ regex_match             Yes        Fails if field does not match the regular
                                    expression.
 required                No         Fails if the field is an empty array, empty
                                    string, null or false.
+required_if             Yes        The field is required when any of the other    ``required_if[field,value1,value2,...]``
+                                   field has the given value. (This rule was 
+                                   added in v4.6.0.)
 required_with           Yes        The field is required when any of the other   ``required_with[field1,field2]``
                                    fields is not `empty()`_ in the data.
 required_without        Yes        The field is required when any of the other   ``required_without[field1,field2]``
-                                   fields is `empty()`_ in the data.
+                                   fields is `empty()`_ in the data. 
 string                  No         A generic alternative to the **alpha*** rules
                                    that confirms the element is a string
 timezone                No         Fails if field does not match a timezone