Feature: add optional and nullable rules

src/Commands/SkipValidationRules.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace StellarWP\Validation\Commands;
+
+/**
+ * Returning this command from ValidationRule::__invoke() tells the Validator to skip all subsequent rules.
+ *
+ * @unreleased
+ */
+class SkipValidationRules
+{
+}

src/Contracts/ValidationRule.php

@@ -5,6 +5,7 @@
 namespace StellarWP\Validation\Contracts;
 
 use Closure;
+use StellarWP\Validation\Commands\SkipValidationRules;
 
 interface ValidationRule
 {
@@ -31,7 +32,7 @@ public static function fromString(string $options = null): ValidationRule;
      *
      * @since 1.0.0
      *
-     * @return void
+     * @return void|SkipValidationRules
      */
     public function __invoke($value, Closure $fail, string $key, array $values);
 }

src/Rules/Nullable.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace StellarWP\Validation\Rules;
+
+use Closure;
+use StellarWP\Validation\Commands\SkipValidationRules;
+use StellarWP\Validation\Contracts\ValidatesOnFrontEnd;
+use StellarWP\Validation\Contracts\ValidationRule;
+
+/**
+ * This rule skips further validation if the field is null. It is similar to Optional, but the only allowed value is
+ * null.
+ *
+ * @unreleased
+ */
+class Nullable implements ValidationRule, ValidatesOnFrontEnd
+{
+    /**
+     * @unreleased
+     */
+    public static function id(): string
+    {
+        return 'nullable';
+    }
+
+    /**
+     * @unreleased
+     */
+    public static function fromString(string $options = null): ValidationRule
+    {
+        return new self();
+    }
+
+    /**
+     * @unreleased
+     *
+     * @return SkipValidationRules|void
+     */
+    public function __invoke($value, Closure $fail, string $key, array $values)
+    {
+        if ($value === null) {
+            return new SkipValidationRules();
+        }
+    }
+
+    /**
+     * @unreleased
+     */
+    public function serializeOption()
+    {
+        return null;
+    }
+}

src/Rules/Optional.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace StellarWP\Validation\Rules;
+
+use Closure;
+use StellarWP\Validation\Commands\SkipValidationRules;
+use StellarWP\Validation\Contracts\ValidatesOnFrontEnd;
+use StellarWP\Validation\Contracts\ValidationRule;
+
+/**
+ * This rule marks a field as optional and skips further validation if the rule is either null or an empty string.
+ *
+ * @unreleased
+ */
+class Optional implements ValidationRule, ValidatesOnFrontEnd
+{
+    /**
+     * @unreleased
+     */
+    public static function id(): string
+    {
+        return 'optional';
+    }
+
+    /**
+     * @unreleased
+     */
+    public static function fromString(string $options = null): ValidationRule
+    {
+        return new self();
+    }
+
+    /**
+     * @unreleased
+     *
+     * @return SkipValidationRules|void
+     */
+    public function __invoke($value, Closure $fail, string $key, array $values)
+    {
+        if ($value === null || $value === '') {
+            return new SkipValidationRules();
+        }
+    }
+
+    /**
+     * @unreleased
+     */
+    public function serializeOption()
+    {
+        return null;
+    }
+}

src/ServiceProvider.php

@@ -9,7 +9,9 @@
 use StellarWP\Validation\Rules\Integer;
 use StellarWP\Validation\Rules\Max;
 use StellarWP\Validation\Rules\Min;
+use StellarWP\Validation\Rules\Nullable;
 use StellarWP\Validation\Rules\Numeric;
+use StellarWP\Validation\Rules\Optional;
 use StellarWP\Validation\Rules\Required;
 use StellarWP\Validation\Rules\Size;
 
@@ -24,6 +26,8 @@ class ServiceProvider
         Integer::class,
         Email::class,
         Currency::class,
+        Nullable::class,
+        Optional::class,
     ];
 
     /**

src/Validator.php

@@ -4,6 +4,7 @@
 
 namespace StellarWP\Validation;
 
+use StellarWP\Validation\Commands\SkipValidationRules;
 use StellarWP\Validation\Contracts\Sanitizer;
 
 /**
@@ -51,8 +52,6 @@ class Validator
      */
     public function __construct(array $ruleSets, array $values, array $labels = [])
     {
-        $this->validateRulesAndValues($ruleSets, $values);
-
         $validatedRules = [];
         foreach ($ruleSets as $key => $rule) {
             if (is_array($rule)) {
@@ -71,24 +70,6 @@ public function __construct(array $ruleSets, array $values, array $labels = [])
         $this->labels = $labels;
     }
 
-    /**
-     * Validates that all rules have a corresponding value with the same key.
-     *
-     * @since 1.0.0
-     *
-     * @return void
-     */
-    private function validateRulesAndValues(array $rules, array $values)
-    {
-        $missingKeys = array_diff_key($rules, $values);
-
-        if (!empty($missingKeys)) {
-            Config::throwInvalidArgumentException(
-                "Missing values for rules: " . implode(', ', array_keys($missingKeys))
-            );
-        }
-    }
-
     /**
      * Returns whether the values failed validation or not.
      *
@@ -134,7 +115,11 @@ private function runValidationRules()
             };
 
             foreach ($ruleSet as $rule) {
-                $rule($value, $fail, $key, $this->values);
+                $command = $rule($value, $fail, $key, $this->values);
+
+                if ($command instanceof SkipValidationRules) {
+                    break;
+                }
 
                 if ($rule instanceof Sanitizer) {
                     $value = $rule->sanitize($value);

tests/_support/Helper/TestCase.php

@@ -66,6 +66,36 @@ public static function assertValidationRuleFailed(
         self::assertValidationRulePassed($rule, $value, $key, $values, false);
     }
 
+    public static function assertValidationRuleDoesReturnCommandInstance(
+        ValidationRule $rule,
+        string $commandClass,
+        $value = null,
+        string $key = '',
+        array $values = []
+    ) {
+        $fail = static function () {
+        };
+
+        $command = $rule($value, $fail, $key, $values);
+
+        self::assertInstanceOf($commandClass, $command);
+    }
+
+    public static function assertValidationRuleDoesNotReturnCommandInstance(
+        ValidationRule $rule,
+        string $commandClass,
+        $value = null,
+        string $key = '',
+        array $values = []
+    ) {
+        $fail = static function () {
+        };
+
+        $command = $rule($value, $fail, $key, $values);
+
+        self::assertNotInstanceOf($commandClass, $command);
+    }
+
     public static function assertIsIterable($actual, $message = '')
     {
         if (\function_exists('is_iterable') === true) {

tests/unit/Rules/NullableTest.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace StellarWP\Validation\Tests\Unit\Rules;
+
+use StellarWP\Validation\Commands\SkipValidationRules;
+use StellarWP\Validation\Rules\Nullable;
+use StellarWP\Validation\Tests\TestCase;
+
+class NullableTest extends TestCase
+{
+    /**
+     * @unreleased
+     */
+    public function testNullableValidation()
+    {
+        $rule = new Nullable();
+
+        // Passes when value is null and skips remaining tests
+        self::assertValidationRulePassed($rule, null);
+        self::assertValidationRuleDoesReturnCommandInstance($rule, SkipValidationRules::class, null);
+
+        // Passes on any other value but does not skip remaining tests
+        self::assertValidationRulePassed($rule, 'bar');
+        self::assertValidationRuleDoesNotReturnCommandInstance($rule, SkipValidationRules::class, 'bar');
+    }
+}

tests/unit/Rules/OptionalTest.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace StellarWP\Validation\Tests\Unit\Rules;
+
+use StellarWP\Validation\Commands\SkipValidationRules;
+use StellarWP\Validation\Rules\Optional;
+use StellarWP\Validation\Tests\TestCase;
+
+class OptionalTest extends TestCase
+{
+    /**
+     * @unreleased
+     */
+    public function testNullableValidation()
+    {
+        $rule = new Optional();
+
+        // Passes when value is null and skips remaining tests
+        self::assertValidationRulePassed($rule, null);
+        self::assertValidationRuleDoesReturnCommandInstance($rule, SkipValidationRules::class, null);
+
+        // Passes when value is empty string and skips remaining tests
+        self::assertValidationRulePassed($rule, '');
+        self::assertValidationRuleDoesReturnCommandInstance($rule, SkipValidationRules::class, '');
+
+        // Passes on any other value but does not skip remaining tests
+        self::assertValidationRulePassed($rule, 'bar');
+        self::assertValidationRuleDoesNotReturnCommandInstance($rule, SkipValidationRules::class, 'bar');
+    }
+}