Invert the behaviour of NotUndef

henriquemoody · henriquemoody · commit 7046560f77af · 2025-12-27T18:49:46.000+01:00
Since we have the ability to use `not` as a prefix, having rules that
start with not becomes a bit inflexible, verbose, and harder to
understand.

This commit will refactor the `NotUndef` rule by inverting its behaviour
and renaming it to `Undef`.
diff --git a/bin/create-mixin b/bin/create-mixin
@@ -26,7 +26,7 @@ use Respect\Validation\Mixins\NotBuilder;
 use Respect\Validation\Mixins\NullOrBuilder;
 use Respect\Validation\Mixins\PropertyBuilder;
 use Respect\Validation\Mixins\UndefOrBuilder;
-use Respect\Validation\Rules\NotUndef;
+use Respect\Validation\Rules\Undef;
 use Respect\Validation\Rules\NullOr;
 use Respect\Validation\Rules\UndefOr;
 use Respect\Validation\Rule;
@@ -172,10 +172,10 @@ function overwriteFile(string $content, string $basename): void
         ['Length', 'length', $numberRelatedRules, []],
         ['Max', 'max', $numberRelatedRules, []],
         ['Min', 'min', $numberRelatedRules, []],
-        ['Not', 'not', [], ['Not', 'NotEmpty', 'NotEmoji', 'NotUndef', 'NullOr', 'UndefOr', 'Attributes', 'Templated', 'Named']],
-        ['NullOr', 'nullOr', [], ['NullOr', 'Blank', 'NotUndef', 'UndefOr', 'Templated', 'Named']],
+        ['Not', 'not', [], ['Not', 'NotEmpty', 'NotEmoji', 'NullOr', 'UndefOr', 'Attributes', 'Templated', 'Named']],
+        ['NullOr', 'nullOr', [], ['NullOr', 'Blank', 'Undef', 'UndefOr', 'Templated', 'Named']],
         ['Property', 'property', [], $structureRelatedRules],
-        ['UndefOr', 'undefOr', [], ['NullOr', 'Blank', 'NotUndef', 'UndefOr', 'Attributes', 'Templated', 'Named']],
+        ['UndefOr', 'undefOr', [], ['NullOr', 'Blank', 'Undef', 'UndefOr', 'Attributes', 'Templated', 'Named']],
         ['', null, [], []],
     ];
 
diff --git a/docs/09-list-of-rules-by-category.md b/docs/09-list-of-rules-by-category.md
@@ -163,8 +163,8 @@
 - [FilterVar](rules/FilterVar.md)
 - [Named](rules/Named.md)
 - [NotEmpty](rules/NotEmpty.md)
-- [NotUndef](rules/NotUndef.md)
 - [Templated](rules/Templated.md)
+- [Undef](rules/Undef.md)
 
 ## Nesting
 
@@ -406,7 +406,6 @@
 - [Not](rules/Not.md)
 - [NotEmoji](rules/NotEmoji.md)
 - [NotEmpty](rules/NotEmpty.md)
-- [NotUndef](rules/NotUndef.md)
 - [NoWhitespace](rules/NoWhitespace.md)
 - [NullOr](rules/NullOr.md)
 - [NullType](rules/NullType.md)
@@ -451,6 +450,7 @@
 - [Tld](rules/Tld.md)
 - [TrueVal](rules/TrueVal.md)
 - [Type](rules/Type.md)
+- [Undef](rules/Undef.md)
 - [UndefOr](rules/UndefOr.md)
 - [Unique](rules/Unique.md)
 - [Uploaded](rules/Uploaded.md)
diff --git a/docs/rules/Attributes.md b/docs/rules/Attributes.md
@@ -10,8 +10,8 @@ Example of object:
 use Respect\Validation\Rules as Rule;
 
 #[Rule\AnyOf(
-    new Rule\Property('email', new Rule\NotUndef()),
-    new Rule\Property('phone', new Rule\NotUndef()),
+    new Rule\Property('email', new Rule\Not(new Rule\Undef())),
+    new Rule\Property('phone', new Rule\Not(new Rule\Undef())),
 )]
 final class Person
 {
diff --git a/docs/rules/Blank.md b/docs/rules/Blank.md
@@ -56,8 +56,8 @@ It's similar to [NotEmpty](NotEmpty.md), but way stricter.
 See also:
 
 - [NotEmpty](NotEmpty.md)
-- [NotUndef](NotUndef.md)
 - [NoWhitespace](NoWhitespace.md)
 - [NullType](NullType.md)
 - [Number](Number.md)
+- [Undef](Undef.md)
 - [UndefOr](UndefOr.md)
diff --git a/docs/rules/NoWhitespace.md b/docs/rules/NoWhitespace.md
@@ -45,5 +45,5 @@ See also:
 - [Blank](Blank.md)
 - [CreditCard](CreditCard.md)
 - [NotEmpty](NotEmpty.md)
-- [NotUndef](NotUndef.md)
+- [Undef](Undef.md)
 - [UndefOr](UndefOr.md)
diff --git a/docs/rules/NotEmpty.md b/docs/rules/NotEmpty.md
@@ -68,8 +68,8 @@ See also:
 - [Each](Each.md)
 - [Max](Max.md)
 - [Min](Min.md)
-- [NotUndef](NotUndef.md)
 - [NoWhitespace](NoWhitespace.md)
 - [NullType](NullType.md)
 - [Number](Number.md)
+- [Undef](Undef.md)
 - [UndefOr](UndefOr.md)
diff --git a/docs/rules/NotUndef.md b/docs/rules/NotUndef.md
diff --git a/docs/rules/NullType.md b/docs/rules/NullType.md
@@ -46,12 +46,12 @@ See also:
 - [FloatType](FloatType.md)
 - [IntType](IntType.md)
 - [NotEmpty](NotEmpty.md)
-- [NotUndef](NotUndef.md)
 - [NullOr](NullOr.md)
 - [Number](Number.md)
 - [ObjectType](ObjectType.md)
 - [ResourceType](ResourceType.md)
 - [StringType](StringType.md)
 - [StringVal](StringVal.md)
 - [Type](Type.md)
+- [Undef](Undef.md)
 - [UndefOr](UndefOr.md)
diff --git a/docs/rules/Number.md b/docs/rules/Number.md
@@ -48,10 +48,10 @@ See also:
 - [FloatType](FloatType.md)
 - [IntType](IntType.md)
 - [NotEmpty](NotEmpty.md)
-- [NotUndef](NotUndef.md)
 - [NullType](NullType.md)
 - [NumericVal](NumericVal.md)
 - [ObjectType](ObjectType.md)
 - [ResourceType](ResourceType.md)
 - [StringType](StringType.md)
 - [Type](Type.md)
+- [Undef](Undef.md)
diff --git a/docs/rules/Undef.md b/docs/rules/Undef.md
@@ -0,0 +1,65 @@
+# Undef
+
+- `Undef()`
+
+Validates if the given input is undefined. By _undefined_ we consider `null` or an empty string (`''`).
+
+```php
+v::undef()->isValid(''); // true
+v::undef()->isValid(null); // true
+```
+
+Other values similar to _undefined_ values are considered _defined_:
+
+```php
+v::undef()->isValid([]); // false
+v::undef()->isValid(' '); // false
+v::undef()->isValid(0); // false
+v::undef()->isValid('0'); // false
+v::undef()->isValid('0.0'); // false
+v::undef()->isValid(false); // false
+v::undef()->isValid(['']); // false
+v::undef()->isValid([' ']); // false
+v::undef()->isValid([0]); // false
+v::undef()->isValid(['0']); // false
+v::undef()->isValid([false]); // false
+v::undef()->isValid([[''], [0]]); // false
+v::undef()->isValid(new stdClass()); // false
+```
+
+## Templates
+
+### `Undef::TEMPLATE_STANDARD`
+
+| Mode       | Template                      |
+| ---------- | ----------------------------- |
+| `default`  | {{subject}} must be undefined |
+| `inverted` | {{subject}} must be defined   |
+
+## Template placeholders
+
+| Placeholder | Description                                                      |
+| ----------- | ---------------------------------------------------------------- |
+| `subject`   | The validated input or the custom validator name (if specified). |
+
+## Categorization
+
+- Miscellaneous
+
+## Changelog
+
+| Version | Description                                 |
+| ------: | ------------------------------------------- |
+|   3.0.0 | Renamed to `Undef` and changed the behavior |
+|   1.0.0 | Created as `NotOptional`                    |
+
+---
+
+See also:
+
+- [Blank](Blank.md)
+- [NotEmpty](NotEmpty.md)
+- [NoWhitespace](NoWhitespace.md)
+- [NullType](NullType.md)
+- [Number](Number.md)
+- [UndefOr](UndefOr.md)
diff --git a/docs/rules/UndefOr.md b/docs/rules/UndefOr.md
@@ -67,7 +67,7 @@ See also:
 
 - [Blank](Blank.md)
 - [NotEmpty](NotEmpty.md)
-- [NotUndef](NotUndef.md)
 - [NoWhitespace](NoWhitespace.md)
 - [NullOr](NullOr.md)
 - [NullType](NullType.md)
+- [Undef](Undef.md)
diff --git a/library/Mixins/Builder.php b/library/Mixins/Builder.php
@@ -248,8 +248,6 @@ public static function notEmoji(): Chain;
 
     public static function notEmpty(): Chain;
 
-    public static function notUndef(): Chain;
-
     public static function nullOr(Rule $rule): Chain;
 
     public static function nullType(): Chain;
@@ -337,6 +335,8 @@ public static function tld(): Chain;
 
     public static function trueVal(): Chain;
 
+    public static function undef(): Chain;
+
     public static function undefOr(Rule $rule): Chain;
 
     public static function unique(): Chain;
diff --git a/library/Mixins/Chain.php b/library/Mixins/Chain.php
@@ -251,8 +251,6 @@ public function notEmoji(): Chain;
 
     public function notEmpty(): Chain;
 
-    public function notUndef(): Chain;
-
     public function nullOr(Rule $rule): Chain;
 
     public function nullType(): Chain;
@@ -340,6 +338,8 @@ public function tld(): Chain;
 
     public function trueVal(): Chain;
 
+    public function undef(): Chain;
+
     public function undefOr(Rule $rule): Chain;
 
     public function unique(): Chain;
diff --git a/library/Mixins/KeyBuilder.php b/library/Mixins/KeyBuilder.php
@@ -227,8 +227,6 @@ public static function keyNotEmoji(int|string $key): Chain;
 
     public static function keyNotEmpty(int|string $key): Chain;
 
-    public static function keyNotUndef(int|string $key): Chain;
-
     public static function keyNullType(int|string $key): Chain;
 
     public static function keyNumber(int|string $key): Chain;
@@ -305,6 +303,8 @@ public static function keyTld(int|string $key): Chain;
 
     public static function keyTrueVal(int|string $key): Chain;
 
+    public static function keyUndef(int|string $key): Chain;
+
     public static function keyUnique(int|string $key): Chain;
 
     public static function keyUploaded(int|string $key): Chain;
diff --git a/library/Mixins/KeyChain.php b/library/Mixins/KeyChain.php
@@ -227,8 +227,6 @@ public function keyNotEmoji(int|string $key): Chain;
 
     public function keyNotEmpty(int|string $key): Chain;
 
-    public function keyNotUndef(int|string $key): Chain;
-
     public function keyNullType(int|string $key): Chain;
 
     public function keyNumber(int|string $key): Chain;
@@ -305,6 +303,8 @@ public function keyTld(int|string $key): Chain;
 
     public function keyTrueVal(int|string $key): Chain;
 
+    public function keyUndef(int|string $key): Chain;
+
     public function keyUnique(int|string $key): Chain;
 
     public function keyUploaded(int|string $key): Chain;
diff --git a/library/Mixins/NotBuilder.php b/library/Mixins/NotBuilder.php
@@ -311,6 +311,8 @@ public static function notTld(): Chain;
 
     public static function notTrueVal(): Chain;
 
+    public static function notUndef(): Chain;
+
     public static function notUnique(): Chain;
 
     public static function notUploaded(): Chain;
diff --git a/library/Mixins/NotChain.php b/library/Mixins/NotChain.php
@@ -311,6 +311,8 @@ public function notTld(): Chain;
 
     public function notTrueVal(): Chain;
 
+    public function notUndef(): Chain;
+
     public function notUnique(): Chain;
 
     public function notUploaded(): Chain;
diff --git a/library/Mixins/PropertyBuilder.php b/library/Mixins/PropertyBuilder.php
@@ -231,8 +231,6 @@ public static function propertyNotEmoji(string $propertyName): Chain;
 
     public static function propertyNotEmpty(string $propertyName): Chain;
 
-    public static function propertyNotUndef(string $propertyName): Chain;
-
     public static function propertyNullType(string $propertyName): Chain;
 
     public static function propertyNumber(string $propertyName): Chain;
@@ -313,6 +311,8 @@ public static function propertyTld(string $propertyName): Chain;
 
     public static function propertyTrueVal(string $propertyName): Chain;
 
+    public static function propertyUndef(string $propertyName): Chain;
+
     public static function propertyUnique(string $propertyName): Chain;
 
     public static function propertyUploaded(string $propertyName): Chain;
diff --git a/library/Mixins/PropertyChain.php b/library/Mixins/PropertyChain.php
@@ -227,8 +227,6 @@ public function propertyNotEmoji(string $propertyName): Chain;
 
     public function propertyNotEmpty(string $propertyName): Chain;
 
-    public function propertyNotUndef(string $propertyName): Chain;
-
     public function propertyNullType(string $propertyName): Chain;
 
     public function propertyNumber(string $propertyName): Chain;
@@ -305,6 +303,8 @@ public function propertyTld(string $propertyName): Chain;
 
     public function propertyTrueVal(string $propertyName): Chain;
 
+    public function propertyUndef(string $propertyName): Chain;
+
     public function propertyUnique(string $propertyName): Chain;
 
     public function propertyUploaded(string $propertyName): Chain;
diff --git a/library/Rules/Undef.php b/library/Rules/Undef.php
diff --git a/library/Transformers/Prefix.php b/library/Transformers/Prefix.php
diff --git a/tests/feature/Rules/NotUndefTest.php b/tests/feature/Rules/NotUndefTest.php
diff --git a/tests/feature/Rules/UndefTest.php b/tests/feature/Rules/UndefTest.php
diff --git a/tests/library/Stubs/WithAttributes.php b/tests/library/Stubs/WithAttributes.php
diff --git a/tests/unit/Rules/UndefTest.php b/tests/unit/Rules/UndefTest.php
diff --git a/tests/unit/Transformers/PrefixTest.php b/tests/unit/Transformers/PrefixTest.php
