Add WhenMissing empty criteria (#500)

vjik · web-flow · commit 62cd3fafdf6b · 2023-01-08T00:06:39.000+04:00
diff --git a/src/EmptyCriteria/WhenMissing.php b/src/EmptyCriteria/WhenMissing.php
@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Validator\EmptyCriteria;
+
+/**
+ * Empty criteria is a callable returning `true` if a value must be considered empty.
+ *
+ * With `WhenMissing` a rule is considered empty only when the value is missing. With regard to validation process, a
+ * corresponding rule is skipped only if this condition is met and `WhenMissing` is set:
+ *
+ * - At a rule level via `$skipOnEmpty` property, but only for rules implementing {@see SkipOnEmptyTrait} / including
+ * {@see SkipOnEmptyTrait}.
+ * - At validator level ({@see Validator::$defaultSkipOnEmptyCriteria}).
+ *
+ * There is no shortcut for this criteria, because it's considered less used. Use new instance directly:
+ * `new WhenMissing()`.
+ */
+final class WhenMissing
+{
+    /**
+     * @param mixed $value The validated value.
+     * @param bool $isAttributeMissing A flag defining whether the attribute is missing (not used / not passed at all).
+     *
+     * @return bool Whether the validated value is considered empty.
+     */
+    public function __invoke(mixed $value, bool $isAttributeMissing): bool
+    {
+        return $isAttributeMissing;
+    }
+}
diff --git a/tests/EmptyCriteria/WhenMissingTest.php b/tests/EmptyCriteria/WhenMissingTest.php
@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Validator\Tests\EmptyCriteria;
+
+use PHPUnit\Framework\TestCase;
+use Yiisoft\Validator\EmptyCriteria\WhenMissing;
+use Yiisoft\Validator\Rule\Number;
+use Yiisoft\Validator\RuleInterface;
+use Yiisoft\Validator\Validator;
+
+final class WhenMissingTest extends TestCase
+{
+    public function dataBase(): array
+    {
+        return [
+            [
+                ['The allowed types are integer, float and string.'],
+                null,
+                new Number(skipOnEmpty: new WhenMissing()),
+            ],
+            [
+                [],
+                [],
+                ['property' => new Number(skipOnEmpty: new WhenMissing())],
+            ],
+            [
+                ['Value must be a number.'],
+                '',
+                new Number(skipOnEmpty: new WhenMissing()),
+            ],
+        ];
+    }
+
+    /**
+     * @dataProvider dataBase
+     */
+    public function testBase(array $expectedMessages, mixed $data, array|RuleInterface|null $rules = null): void
+    {
+        $result = (new Validator())->validate($data, $rules);
+
+        $this->assertSame($expectedMessages, $result->getErrorMessages());
+    }
+}
