Merge pull request #18 from programmatordev/YAPV-12-create-documentation

Create documentation

Author: andrepimpao

README.md

@@ -1,6 +1,6 @@
 # Yet Another PHP Validator
 
-Focused on validating development code with expressive error messages.
+Versatile library focused on validating development code with expressive error messages.
 
 ## Requirements
 
@@ -25,12 +25,21 @@ require_once 'vendor/autoload.php';
 Simple usage looks like:
 
 ```php
+use ProgrammatorDev\YetAnotherPhpValidator\Rule;
 use ProgrammatorDev\YetAnotherPhpValidator\Validator;
 
-$ageValidator = Validator::notBlank()->greaterThanOrEqual(18);
+// Do this...
+$validator = Validator::notBlank()->greaterThanOrEqual(18);
 
-$ageValidator->validate(16); // returns false
-$ageValidator->assert(16, 'Age'); // throws exception: The "Age" value should be greater than or equal to "18", "16" given.
+// ...or this...
+$validator = new Validator(
+    new Rule\NotBlank(), 
+    new Rule\GreaterThanOrEqual(18)
+);
+
+// ...and validate with these:
+$validator->validate(16); // returns bool: false
+$validator->assert(16, 'Age'); // throws exception: The "Age" value should be greater than or equal to "18", "16" given.
 ```
 
 ## Documentation

docs/01-get-started.md

@@ -0,0 +1,50 @@
+# Get Started
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Basic Usage](#basic-usage)
+
+## Requirements
+
+- PHP 8.1 or higher.
+
+## Installation
+
+You can 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:
+
+```php
+use ProgrammatorDev\YetAnotherPhpValidator\Rule;
+use ProgrammatorDev\YetAnotherPhpValidator\Validator;
+
+// Do this...
+$validator = Validator::notBlank()->greaterThanOrEqual(18);
+
+// ...or this...
+$validator = new Validator(
+    new Rule\NotBlank(), 
+    new Rule\GreaterThanOrEqual(18)
+);
+
+// ...or even this...
+$validator = (new Validator())
+    ->addRule(new Rule\NotBlank())
+    ->addRule(new Rule\GreaterThanOrEqual(18));
+
+// ...and validate with these:
+$validator->validate(16); // returns bool: false
+$validator->assert(16, 'Age'); // throws exception: The "Age" value should be greater than or equal to "18", "16" given.
+```

docs/02-usage.md

@@ -0,0 +1,100 @@
+# Using Yet Another PHP Validator
+
+- Usage
+  - Fluent
+  - Dependency Injection
+- Validation
+  - assert
+  - validate
+
+## Usage
+
+### Fluent
+
+```php
+use ProgrammatorDev\YetAnotherPhpValidator\Exception\ValidationException;
+use ProgrammatorDev\YetAnotherPhpValidator\Validator;
+
+/**
+ * @throws ValidationException
+ */
+function getWeatherTemperature(float $latitude, float $longitude, string $unitSystem): float
+{
+    Validator::range(-90, 90)->assert($latitude, 'Latitude');
+    Validator::range(-180, 180)->assert($longitude, 'Longitude');
+    Validator::notBlank()->choice(['METRIC', 'IMPERIAL'])->assert($unitSystem, 'Unit System');
+    
+    // ...
+}
+```
+
+### Dependency Injection
+
+```php
+use ProgrammatorDev\YetAnotherPhpValidator\Exception\ValidationException;
+use ProgrammatorDev\YetAnotherPhpValidator\Rule;
+use ProgrammatorDev\YetAnotherPhpValidator\Validator;
+
+/**
+ * @throws ValidationException
+ */
+function getWeatherTemperature(float $latitude, float $longitude, string $unitSystem): float
+{
+    (new Validator(new Rule\Range(-90, 90)))
+        ->assert($latitude, 'Latitude');
+    (new Validator(new Rule\Range(-180, 180)))
+        ->assert($longitude, 'Longitude');
+    (new Validator(new Rule\NotBlank(), new Rule\Choice(['METRIC', 'IMPERIAL'])))
+        ->assert($unitSystem, 'Unit System');
+
+    // ...
+}
+```
+
+A `addRule` method is also available that may be useful for conditional rules:
+
+```php
+use ProgrammatorDev\YetAnotherPhpValidator\Rule;
+use ProgrammatorDev\YetAnotherPhpValidator\Validator;
+
+function calculateDiscount(float $price, float $discount, string $type): float
+{
+    $discountValidator = new Validator(new GreaterThan(0));
+    
+    if ($type === 'PERCENT') {
+        $discountValidator->addRule(new Rule\LessThanOrEqual(100));
+    }
+    
+    $discountValidator->assert($discount, 'Discount');
+    
+    // ...
+}
+```
+
+## Validation
+
+### `assert`
+
+```php
+use ProgrammatorDev\YetAnotherPhpValidator\Exception\ValidationException;
+use ProgrammatorDev\YetAnotherPhpValidator\Validator;
+
+// function getWeatherTemperature(float $latitude, float $longitude, string $unitSystem)
+
+try {
+    getWeatherTemperature(100, 50, 'METRIC');
+}
+catch (ValidationException $exception) {
+    echo $exception->getMessage(); // The "Latitude" value should be between "-90" and "90", "100" given.
+}
+```
+
+### `validate`
+
+```php
+use ProgrammatorDev\YetAnotherPhpValidator\Validator;
+
+if (!Validator::range(-90, 90)->validate($latitude)) {
+    // do something...
+} 
+```

docs/03-rules-notblank.md

@@ -0,0 +1,42 @@
+# NotBlank
+
+Validates that a value is not equal to a blank string, blank array, `false` or `null`.
+
+## Basic Usage
+
+```php
+Validator::notBlank()->validate(''); // false
+Validator::notBlank()->validate([]); // false
+Validator::notBlank()->validate(false); // false
+Validator::notBlank()->validate(null); // false
+```
+
+## Options
+
+```php
+use ProgrammatorDev\YetAnotherPhpValidator\Rule;
+
+// Defaults
+new Rule\NotBlank(
+    array $options = [
+        'normalizer' => null,
+        'message' => 'The "{{ name }}" value should not be blank, "{{ value }}" given.'
+    ]  
+);
+```
+
+### `options`
+
+type: `array`
+
+`normalizer` 
+
+type: `callable` default: `null`
+
+`message`
+
+type: `string` default: `The "{{ name }}" value should not be blank, "{{ value }}" given.`
+
+
+
+Normalizer

docs/03-rules.md

@@ -0,0 +1,14 @@
+# Rules
+
+- Basic Constraints
+  - NotBlank
+- Comparison Constraints
+  - LessThan
+  - LessThanOrEqual
+  - GreaterThan
+  - GreaterThanOrEqual
+  - Range
+- Choice Constraints
+  - Choice
+- Other Constraints
+  - All

src/Rule/AbstractComparisonRule.php

@@ -18,7 +18,7 @@ public function assert(mixed $value, string $name): void
             );
         }
 
-        if (!$this->comparison($value, $this->constraint)) {
+        if (!$this->compareValues($value, $this->constraint)) {
             throw new ($this->getException())(
                 message: $this->options['message'],
                 parameters: [
@@ -30,7 +30,7 @@ public function assert(mixed $value, string $name): void
         }
     }
 
-    protected abstract function comparison(mixed $value1, mixed $value2): bool;
+    protected abstract function compareValues(mixed $value1, mixed $value2): bool;
 
     protected abstract function getException(): string;
 }

src/Rule/GreaterThan.php

@@ -23,7 +23,7 @@ public function __construct(
         $this->options = $resolver->resolve($options);
     }
 
-    protected function comparison(mixed $value1, mixed $value2): bool
+    protected function compareValues(mixed $value1, mixed $value2): bool
     {
         if (\is_string($value1) && \is_string($value2)) {
             return strcmp($value1, $value2) > 0;

src/Rule/GreaterThanOrEqual.php

@@ -23,7 +23,7 @@ public function __construct(
         $this->options = $resolver->resolve($options);
     }
 
-    protected function comparison(mixed $value1, mixed $value2): bool
+    protected function compareValues(mixed $value1, mixed $value2): bool
     {
         if (\is_string($value1) && \is_string($value2)) {
             return strcmp($value1, $value2) >= 0;

src/Rule/LessThan.php

@@ -23,7 +23,7 @@ public function __construct(
         $this->options = $resolver->resolve($options);
     }
 
-    protected function comparison(mixed $value1, mixed $value2): bool
+    protected function compareValues(mixed $value1, mixed $value2): bool
     {
         if (\is_string($value1) && \is_string($value2)) {
             return strcmp($value1, $value2) < 0;

src/Rule/LessThanOrEqual.php

@@ -23,7 +23,7 @@ public function __construct(
         $this->options = $resolver->resolve($options);
     }
 
-    protected function comparison(mixed $value1, mixed $value2): bool
+    protected function compareValues(mixed $value1, mixed $value2): bool
     {
         if (\is_string($value1) && \is_string($value2)) {
             return strcmp($value1, $value2) <= 0;