chore: added the error handling section

Author: andrepimpao

docs/02-usage.md

@@ -1,19 +1,19 @@
 # Using Yet Another PHP Validator
 
-- Usage
-  - Fluent
-  - Dependency Injection
-- Methods
-  - assert
-  - validate
-  - getRules
-  - addRule
-- Exception Handling
-- Custom Exception Messages
+- [Usage](#usage)
+  - [Fluent](#fluent)
+  - [Dependency Injection](#dependency-injection)
+- [Methods](#methods)
+  - [assert](#assert)
+  - [validate](#validate)
+  - [getRules](#getrules)
+  - [addRule](#addrule)
+- [Error Handling](#error-handling)
+- [Custom Error Messages](#custom-error-messages)
 
 ## Usage
 
-This library allows you to use validate data in two different ways:
+This library allows you to validate data in two different ways:
 - In a fluent way, making use of magic methods. The goal is to be able to create a set of rules with minimum setup;
 - In a traditional way, making use of dependency injection. You may not like the fluent approach, and prefer to work this way.
 
@@ -71,7 +71,7 @@ This method throws a `ValidationException` when a rule fails, otherwise nothing
 assert(mixed $value, string $name): void;
 ```
 
-An example on how to handle an exception:
+An example on how to handle an error:
 
 ```php
 use ProgrammatorDev\YetAnotherPhpValidator\Exception\ValidationException;
@@ -93,9 +93,11 @@ catch (ValidationException $exception) {
     echo $exception->getMessage(); // The "Latitude" value should be between "-90" and "90", "100" given.
 }
 ```
+> **Note**
+> Check the [Error Handling](#error-handling) section for more information.
 
 > **Note**
-> The example only shows one usage approach, but both Fluent and Dependency Injection usage approaches should work the same.
+> The example only shows one usage approach, but both Fluent and Dependency Injection should work the same.
 > Check the [Usage](#usage) section for more information.
 
 ### `validate`
@@ -117,7 +119,7 @@ if (!Validator::range(-90, 90)->validate($latitude)) {
 ```
 
 > **Note**
-> The example only shows one usage approach, but both Fluent and Dependency Injection usage approaches should work the same.
+> The example only shows one usage approach, but both Fluent and Dependency Injection should work the same.
 > Check the [Usage](#usage) section for more information.
 
 ### `getRules`
@@ -148,7 +150,7 @@ print_r($validator->getRules());
 ```
 
 > **Note**
-> The example only shows one usage approach, but both Fluent and Dependency Injection usage approaches should work the same.
+> The example only shows one usage approach, but both Fluent and Dependency Injection should work the same.
 > Check the [Usage](#usage) section for more information.
 
 ### `addRule`
@@ -180,16 +182,74 @@ function calculateDiscount(float $price, float $discount, string $type): float
 ```
 
 > **Note**
-> The example only shows one usage approach, but both Fluent and Dependency Injection usage approaches should work the same. 
+> The example only shows one usage approach, but both Fluent and Dependency Injection should work the same.
 > Check the [Usage](#usage) section for more information.
 
-## Exception Handling
+## Error Handling
+
+When using the [`assert`](#assert) method to validate a value, an exception is thrown when a rule fails.
+
+Each rule has a unique exception, formed by the name of the rule plus Exception — `RuleNameException`.
+The following shows an example:
+
+```php
+use ProgrammatorDev\YetAnotherPhpValidator\Exception;
+use ProgrammatorDev\YetAnotherPhpValidator\Validator;
+
+try {
+    Validator::range(-90, 90)->assert($latitude, 'Latitude');
+    Validator::range(-180, 180)->assert($longitude, 'Longitude');
+    Validator::notBlank()->choice(['METRIC', 'IMPERIAL'])->assert($unitSystem, 'Unit System');
+}
+catch (Exception\RangeException $exception) {
+    // Do something when Range fails
+}
+catch (Exception\NotBlankException $exception) {
+    // Do something when NotBlank fails
+}
+catch (Exception\ChoiceException $exception) {
+    // Do something when Choice fails
+}
+```
+
+To catch all errors with a single exception, you can use the `ValidationException`:
+
+```php
+use ProgrammatorDev\YetAnotherPhpValidator\Exception\ValidationException;
+use ProgrammatorDev\YetAnotherPhpValidator\Validator;
+
+try {
+    Validator::range(-90, 90)->assert($latitude, 'Latitude');
+    Validator::range(-180, 180)->assert($longitude, 'Longitude');
+    Validator::notBlank()->choice(['METRIC', 'IMPERIAL'])->assert($unitSystem, 'Unit System');
+}
+catch (ValidationException $exception) {
+    // Do something when a rule fails
+}
+```
+
+An `UnexpectedValueException` is thrown when the provided input data is not valid to perform the validation. 
+For example, when trying to compare a date with a string:
+
+```php
+use ProgrammatorDev\YetAnotherPhpValidator\Exception\UnexpectedValueException;
+use ProgrammatorDev\YetAnotherPhpValidator\Validator;
+
+try {
+    Validator::greaterThanOrEqual(new DateTime('today'))->validate('alpha');
+}
+catch (UnexpectedValueException $exception) {
+    echo $exception->getMessage(); // Cannot compare a type "string" with a type "DateTime".
+}
+```
+
+This exception is thrown when using [`assert`](#assert) or [`validate`](#validate).
 
-## Custom Exception Messages
+## Custom Error Messages
 
 All rules have at least one error message that can be customized (some rules have more than one error message for different case scenarios).
 
-Every message has a list of dynamic parameters to help create an intuitive error text (like the invalid value, constraints, names, and others).
+Every message has a list of dynamic parameters to help create an intuitive error (like the invalid value, constraints, names, and others).
 To check what parameters and messages are available, look into the Options section in the page of a rule. 
 Go to [Rules](03-rules.md) to see all available rules.
 

docs/03-rules.md

@@ -3,7 +3,7 @@
 - [Basic Rules](#basic-rules)
 - [Comparison Rules](#comparison-rules)
 - [Choice Rules](#choice-rules)
-- [Array Rules](#array-rules)
+- [Other Rules](#other-rules)
 
 ## Basic Rules
 
@@ -21,6 +21,6 @@
 
 - [Choice](03x-rules-choice.md)
 
-## Array Rules
+## Other Rules
 
 - [All](03x-rules-all.md)