Merge pull request #69 from programmatordev/YAPV-54-create-blank-rule

Create Blank rule

Author: andrepimpao

README.md

@@ -12,18 +12,12 @@ PHP validator with expressive error messages.
 
 ## Installation
 
-You can install the library via [Composer](https://getcomposer.org/):
+Install the library via [Composer](https://getcomposer.org/):
 
 ```bash
 composer require programmatordev/yet-another-php-validator
 ```
 
-To use the library, use Composer's [autoload](https://getcomposer.org/doc/01-basic-usage.md#autoloading):
-
-```php
-require_once 'vendor/autoload.php';
-```
-
 ## Basic Usage
 
 Simple usage looks like:

docs/01-get-started.md

@@ -10,18 +10,12 @@
 
 ## Installation
 
-You can install the library via [Composer](https://getcomposer.org/):
+Install the library via [Composer](https://getcomposer.org/):
 
 ```bash
 composer require programmatordev/yet-another-php-validator
 ```
 
-To use the library, use Composer's [autoload](https://getcomposer.org/doc/01-basic-usage.md#autoloading):
-
-```php
-require_once 'vendor/autoload.php';
-```
-
 ## Basic Usage
 
 Simple usage looks like:

docs/03-rules.md

@@ -10,6 +10,7 @@
 
 ## Basic Rules
 
+- [Blank](03-rules_blank.md)
 - [Count](03-rules_count.md)
 - [NotBlank](03-rules_not-blank.md)
 - [Type](03-rules_type.md)

docs/03-rules_blank.md

@@ -0,0 +1,56 @@
+# Blank
+
+Validates that a value is equal to an empty string, empty array, `false` or `null`.
+
+Check the [NotBlank](03-rules_not-blank.md) rule for the opposite validation.
+
+```php
+Blank(
+    ?callable $normalizer = null,
+    ?string $message = null
+);
+```
+
+## Basic Usage
+
+Bellow are the *only* cases where the rule will succeed by default, 
+everything else is considered invalid (you may want to check the [`normalizer`](#normalizer) option for a different behaviour):
+
+```php
+Validator::blank()->validate(''); // true
+Validator::blank()->validate([]); // true
+Validator::blank()->validate(false); // true
+Validator::blank()->validate(null); // true
+```
+
+## Options
+
+### `normalizer`
+
+type: `?callable` default: `null`
+
+Allows to define a `callable` that will be applied to the value before checking if it is valid.
+
+For example, use `trim`, or pass your own function, to allow a string with whitespaces only:
+
+```php
+Validator::blank(normalizer: 'trim')->validate(' '); // true
+Validator::blank(normalizer: fn($value) => trim($value))->validate(' '); // true
+```
+
+### `message`
+
+type: `?string` default: `The {{ name }} value should be blank, {{ value }} given.`
+
+Message that will be shown if the value is not blank.
+
+The following parameters are available:
+
+| Parameter     | Description               |
+|---------------|---------------------------|
+| `{{ value }}` | The current invalid value |
+| `{{ name }}`  | Name of the invalid value |
+
+## Changelog
+
+- `1.2.0` Created

docs/03-rules_not-blank.md

@@ -1,6 +1,8 @@
 # NotBlank
 
-Validates that a value is not equal to a blank string, blank array, `false` or `null`.
+Validates that a value is not equal to an empty string, empty array, `false` or `null`.
+
+Check the [Blank](03-rules_blank.md) rule for the opposite validation.
 
 ```php
 NotBlank(
@@ -25,17 +27,14 @@ Validator::notBlank()->validate(null); // false
 
 ### `normalizer`
 
-type: `callable` default: `null`
+type: `?callable` default: `null`
 
 Allows to define a `callable` that will be applied to the value before checking if it is valid.
 
 For example, use `trim`, or pass your own function, to not allow a string with whitespaces only:
 
 ```php
-// Existing PHP callables
 Validator::notBlank(normalizer: 'trim')->validate(' '); // false
-
-// Function
 Validator::notBlank(normalizer: fn($value) => trim($value))->validate(' '); // false
 ```
 

src/ChainedValidatorInterface.php

@@ -7,6 +7,11 @@
 
 interface ChainedValidatorInterface
 {
+    public function blank(
+        ?callable $normalizer = null,
+        ?string $message = null
+    ): ChainedValidatorInterface&Validator;
+
     public function choice(
         array $constraints,
         bool $multiple = false,

src/Exception/BlankException.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace ProgrammatorDev\Validator\Exception;
+
+class BlankException extends ValidationException {}

src/Rule/Blank.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace ProgrammatorDev\Validator\Rule;
+
+use ProgrammatorDev\Validator\Exception\BlankException;
+
+class Blank extends AbstractRule implements RuleInterface
+{
+    /** @var ?callable */
+    private $normalizer;
+    private string $message = 'The {{ name }} value should be blank, {{ value }} given.';
+
+    public function __construct(
+        ?callable $normalizer = null,
+        ?string $message = null
+    )
+    {
+        $this->normalizer = $normalizer;
+        $this->message = $message ?? $this->message;
+    }
+
+    public function assert(mixed $value, ?string $name = null): void
+    {
+        if ($this->normalizer !== null) {
+            $value = ($this->normalizer)($value);
+        }
+
+        if ($value !== null && $value !== false && $value !== '' && $value !== []) {
+            throw new BlankException(
+                message: $this->message,
+                parameters: [
+                    'value' => $value,
+                    'name' => $name
+                ]
+            );
+        }
+    }
+}

src/Rule/NotBlank.php

@@ -3,6 +3,7 @@
 namespace ProgrammatorDev\Validator\Rule;
 
 use ProgrammatorDev\Validator\Exception\NotBlankException;
+use ProgrammatorDev\Validator\Validator;
 
 class NotBlank extends AbstractRule implements RuleInterface
 {
@@ -19,17 +20,9 @@ public function __construct(
         $this->message = $message ?? $this->message;
     }
 
-    /**
-     * @throws NotBlankException
-     */
     public function assert(mixed $value, ?string $name = null): void
     {
-        if ($this->normalizer !== null) {
-            $value = ($this->normalizer)($value);
-        }
-
-        // Do not allow null, false, [] and ''
-        if ($value === false || (empty($value) && $value != '0')) {
+        if (Validator::blank(normalizer: $this->normalizer)->validate($value) === true) {
             throw new NotBlankException(
                 message: $this->message,
                 parameters: [

src/StaticValidatorInterface.php

@@ -6,6 +6,11 @@
 
 interface StaticValidatorInterface
 {
+    public static function blank(
+        ?callable $normalizer = null,
+        ?string $message = null
+    ): ChainedValidatorInterface&Validator;
+
     public static function choice(
         array $constraints,
         bool $multiple = false,

tests/BlankTest.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace ProgrammatorDev\Validator\Test;
+
+use ProgrammatorDev\Validator\Exception\BlankException;
+use ProgrammatorDev\Validator\Rule\Blank;
+use ProgrammatorDev\Validator\Test\Util\TestRuleMessageOptionTrait;
+use ProgrammatorDev\Validator\Test\Util\TestRuleFailureConditionTrait;
+use ProgrammatorDev\Validator\Test\Util\TestRuleSuccessConditionTrait;
+
+class BlankTest extends AbstractTest
+{
+    use TestRuleFailureConditionTrait;
+    use TestRuleSuccessConditionTrait;
+    use TestRuleMessageOptionTrait;
+
+    public static function provideRuleFailureConditionData(): \Generator
+    {
+        $exception = BlankException::class;
+        $message = '/The (.*) value should be blank, (.*) given\./';
+
+        yield 'true' => [new Blank(), true, $exception, $message];
+
+        yield 'string' => [new Blank(), 'string', $exception, $message];
+        yield 'whitespace string' => [new Blank(), ' ', $exception, $message];
+        yield 'zero string' => [new Blank(), '0', $exception, $message];
+
+        yield 'array' => [new Blank(), ['string'], $exception, $message];
+        yield 'blank string array' => [new Blank(), [''], $exception, $message];
+        yield 'whitespace array' => [new Blank(), [' '], $exception, $message];
+        yield 'zero array' => [new Blank(), [0], $exception, $message];
+
+        yield 'number' => [new Blank(), 10, $exception, $message];
+        yield 'zero number' => [new Blank(), 0, $exception, $message];
+    }
+
+    public static function provideRuleSuccessConditionData(): \Generator
+    {
+        yield 'null' => [new Blank(), null];
+        yield 'false' => [new Blank(), false];
+        yield 'blank string' => [new Blank(), ''];
+        yield 'blank array' => [new Blank(), []];
+
+        yield 'normalizer whitespace' => [new Blank(normalizer: 'trim'), ' '];
+        yield 'normalizer whitespace function' => [new Blank(normalizer: fn($value) => trim($value)), ' '];
+    }
+
+    public static function provideRuleMessageOptionData(): \Generator
+    {
+        yield 'message' => [
+            new Blank(message: '{{ name }} | {{ value }}'),
+            'string',
+            'test | "string"'
+        ];
+    }
+}