Refactor the "UndefOr" rule and related classes

This commit will rename the "Optional" rule to"UndefOr" while soft
deprecating the old name. It should work the same as the previous one
but with a different name. It will also prefix the result ID, allowing
more message customization.

While working on it, I realized that the prefix "undefOr" had a typo,
and it was using "undefOf" instead. I fixed that, too.

Signed-off-by: Henrique Moody <[email protected]>

bin/create-mixin

@@ -25,9 +25,11 @@ use Respect\Validation\Mixins\StaticNot;
 use Respect\Validation\Mixins\StaticNullOr;
 use Respect\Validation\Mixins\StaticProperty;
 use Respect\Validation\Mixins\StaticUndefOr;
+use Respect\Validation\Rules\UndefOr;
 use Respect\Validation\Validatable;
 
 function addMethodToInterface(
+ string $originalName,
  InterfaceType $interfaceType,
  ReflectionClass $reflection,
  ?string $prefix,
@@ -42,7 +44,7 @@ function addMethodToInterface(
  return;
  }
 
- $name = $prefix ? $prefix . ucfirst($reflection->getShortName()) : lcfirst($reflection->getShortName());
+ $name = $prefix ? $prefix . ucfirst($originalName) : lcfirst($originalName);
  $method = $interfaceType->addMethod($name)->setPublic()->setReturnType(ChainedValidator::class);
  if (str_starts_with($interfaceType->getName(), 'Static')) {
  $method->setStatic();
@@ -65,6 +67,10 @@ function addMethodToInterface(
  $method->addComment(preg_replace('@(/\*\* *| +\* +| +\*/)@', '', $commend));
  }
 
+ if ($originalName === 'Optional') {
+ $method->addComment('@deprecated Use {@see undefOr()} instead.');
+ }
+
  foreach ($reflrectionConstructor->getParameters() as $reflectionParameter) {
  if ($reflectionParameter->isVariadic()) {
  $method->setVariadic();
@@ -150,6 +156,8 @@ function overwriteFile(string $content, string $basename): void
  'KeyExists',
  'KeyOptional',
  'KeySet',
+ 'Optional',
+ 'UndefOr',
  'Property',
  'PropertyExists',
  'PropertyOptional',
@@ -160,10 +168,10 @@ function overwriteFile(string $content, string $basename): void
  ['Length', 'length', $numberRelatedRules, []],
  ['Max', 'max', $numberRelatedRules, []],
  ['Min', 'min', $numberRelatedRules, []],
- ['Not', 'not', [], ['Not', 'NotEmpty', 'NotBlank', 'NotEmoji', 'NotOptional', 'Optional']],
- ['NullOr', 'nullOf', [], ['Nullable', 'Optional']],
+ ['Not', 'not', [], ['Not', 'NotEmpty', 'NotBlank', 'NotEmoji', 'NotOptional', 'UndefOr', 'Optional']],
+ ['NullOr', 'nullOf', [], ['Nullable', 'Optional', 'UndefOr']],
  ['Property', 'property', [], $structureRelatedRules],
- ['UndefOr', 'undefOf', [], ['Nullable', 'Optional']],
+ ['UndefOr', 'undefOr', [], ['Nullable', 'Optional', 'UndefOr']],
  ['Validator', null, [], []],
  ];
 
@@ -179,6 +187,9 @@ function overwriteFile(string $content, string $basename): void
  continue;
  }
  $names[$reflection->getShortName()] = $reflection;
+ if ($className === UndefOr::class) {
+ $names['Optional'] = $reflection;
+ }
  }
  ksort($names);
 
@@ -212,9 +223,9 @@ function overwriteFile(string $content, string $basename): void
  $staticInterface->addExtend(StaticUndefOr::class);
  }
 
- foreach ($names as $reflection) {
- addMethodToInterface($staticInterface, $reflection, $prefix, $allowList, $denyList);
- addMethodToInterface($chainedInterface, $reflection, $prefix, $allowList, $denyList);
+ foreach ($names as $originalName => $reflection) {
+ addMethodToInterface($originalName, $staticInterface, $reflection, $prefix, $allowList, $denyList);
+ addMethodToInterface($originalName, $chainedInterface, $reflection, $prefix, $allowList, $denyList);
  }
 
  $printer = new Printer();

docs/rules/UndefOr.md

@@ -0,0 +1,45 @@
+# UndefOr
+
+- `UndefOr(Validatable $rule)`
+
+Validates if the given input is undefined or not.
+
+By _undefined_ we consider `null` or an empty string (`''`), which implies that the input is not set. This is particularly useful when validating form fields
+
+```php
+v::undefOr(v::alpha())->validate(''); // true
+v::undefOr(v::digit())->validate(null); // true
+
+v::undefOr(v::alpha())->validate('username'); // true
+v::undefOr(v::alpha())->validate('has1number'); // false
+```
+
+## Note
+
+For convenience, you can use the `undefOr` as a prefix to any rule:
+
+```php
+v::undefOrEmail()->validate('not an email'); // false
+v::undefOrBetween(1, 3)->validate(2); // true
+```
+
+## Categorization
+
+- Nesting
+
+## Changelog
+
+| Version | Description |
+|--------:|--------------------------------------|
+| 3.0.0 | Renamed from "Optional" to "UndefOr" |
+| 1.0.0 | Created |
+
+***
+See also:
+
+- [NoWhitespace](NoWhitespace.md)
+- [NotBlank](NotBlank.md)
+- [NotEmpty](NotEmpty.md)
+- [NotOptional](NotOptional.md)
+- [NullType](NullType.md)
+- [Nullable](Nullable.md)

library/Factory.php

@@ -17,6 +17,7 @@
 use Respect\Validation\Message\Parameter\Raw;
 use Respect\Validation\Message\Parameter\Stringify;
 use Respect\Validation\Message\Parameter\Trans;
+use Respect\Validation\Transformers\Aliases;
 use Respect\Validation\Transformers\DeprecatedAttribute;
 use Respect\Validation\Transformers\DeprecatedKey;
 use Respect\Validation\Transformers\DeprecatedKeyNested;
@@ -59,7 +60,7 @@ public function __construct()
  new DeprecatedKey(
  new DeprecatedKeyValue(
  new DeprecatedMinAndMax(
- new DeprecatedKeyNested(new DeprecatedLength(new DeprecatedType(new Prefix())))
+ new DeprecatedKeyNested(new DeprecatedLength(new DeprecatedType(new Aliases(new Prefix()))))
  )
  )
  )

library/Mixins/ChainedKey.php

@@ -274,8 +274,6 @@ public function keyOneOf(
  Validatable ...$rules,
  ): ChainedValidator;
 
- public function keyOptional(int|string $key, Validatable $rule): ChainedValidator;
-
  public function keyPerfectSquare(int|string $key): ChainedValidator;
 
  public function keyPesel(int|string $key): ChainedValidator;

library/Mixins/ChainedProperty.php

@@ -286,8 +286,6 @@ public function propertyOneOf(
  Validatable ...$rules,
  ): ChainedValidator;
 
- public function propertyOptional(string $propertyName, Validatable $rule): ChainedValidator;
-
  public function propertyPerfectSquare(string $propertyName): ChainedValidator;
 
  public function propertyPesel(string $propertyName): ChainedValidator;