feat(docs): added Email rule documentation

Author: andrepimpao

docs/03x-rules-choice.md

@@ -78,7 +78,7 @@ For example, if `maxConstraint` is 2, the input array must have at most 2 values
 
 ### `message`
 
-type `string` default: `The {{ name }} value is not a valid choice, {{ value }} given. Accepted values are: {{ constraints }}.`
+type: `string` default: `The {{ name }} value is not a valid choice, {{ value }} given. Accepted values are: {{ constraints }}.`
 
 Message that will be shown if input value is not a valid choice.
 
@@ -92,7 +92,7 @@ The following parameters are available:
 
 ### `multipleMessage`
 
-type `string` default: `The {{ name }} value has one or more invalid choices, {{ value }} given. Accepted values are: {{ constraints }}.`
+type: `string` default: `The {{ name }} value has one or more invalid choices, {{ value }} given. Accepted values are: {{ constraints }}.`
 
 Message that will be shown when `multiple` is `true` and at least one of the input array values is not a valid choice.
 
@@ -106,7 +106,7 @@ The following parameters are available:
 
 ### `minMessage`
 
-type `string` default: `The {{ name }} value must have at least {{ minConstraint }} choices, {{ numValues }} choices given.`
+type: `string` default: `The {{ name }} value must have at least {{ minConstraint }} choices, {{ numValues }} choices given.`
 
 Message that will be shown when `multiple` is `true` and input array has fewer values than the defined in `minConstraint`.
 
@@ -123,7 +123,7 @@ The following parameters are available:
 
 ### `maxMessage`
 
-type `string` default: `The {{ name }} value must have at most {{ maxConstraint }} choices, {{ numValues }} choices given.`
+type: `string` default: `The {{ name }} value must have at most {{ maxConstraint }} choices, {{ numValues }} choices given.`
 
 Message that will be shown when `multiple` is `true` and input array has more values than the defined in `maxConstraint`.
 

docs/03x-rules-email.md

@@ -0,0 +1,73 @@
+# Email
+
+Validates that a value is a valid email address.
+
+```php
+Email(
+    string $mode = 'html5',
+    ?callable $normalizer = null,
+    string $message = 'The {{ name }} value is not a valid email address, {{ value }} given.'
+);
+```
+
+## Basic Usage
+
+```php
+// html5 mode (default)
+Validator::email()->validate('test@example.com'); // true
+Validator::email()->validate('test@example'); // false
+
+// html5-allow-no-tld mode
+Validator::email(mode: 'html5-allow-no-tld')->validate('test@example.com'); // true
+Validator::email(mode: 'html5-allow-no-tld')->validate('test@example'); // true
+```
+
+> **Note**
+> An `UnexpectedValueException` will be thrown when a `mode` option is invalid.
+
+## Options
+
+### `mode`
+
+type: `string` default: `html5`
+
+Set this option to define the validation mode.
+
+Available options are:
+
+- `html5` uses the regular expression of an HTML5 email input element, but enforces it to have a TLD extension.
+- `html5-allow-no-tld` uses the regular expression of an HTML5 email input element, which allows addresses without a TLD extension.
+- `strict` validates an address according to the [RFC 5322](https://datatracker.ietf.org/doc/html/rfc5322) specification.
+
+### `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 ignore whitespace in the beginning or end of an email address:
+
+```php
+Validator::email()->validate('test@example.com '); // false
+
+Validator::email(normalizer: 'trim')->validate('test@example.com '); // true
+Validator::email(normalizer: fn($value) => trim($value))->validate('test@example.com '); // true
+```
+
+### `message`
+
+type `string` default: `The {{ name }} value is not a valid email address, {{ value }} given.`
+
+Message that will be shown if the input value is not a valid email address.
+
+The following parameters are available:
+
+| Parameter     | Description               |
+|---------------|---------------------------|
+| `{{ value }}` | The current invalid value |
+| `{{ name }}`  | Name of the invalid value |
+| `{{ mode }}`  | Selected validation mode  |
+
+## Changelog
+
+- `0.6.0` Created

docs/03x-rules-timezone.md

@@ -75,7 +75,7 @@ Check the [official country codes](https://en.wikipedia.org/wiki/ISO_3166-1#Curr
 
 ### `message`
 
-type `string` default: `The {{ name }} value is not a valid timezone, {{ value }} given.`
+type: `string` default: `The {{ name }} value is not a valid timezone, {{ value }} given.`
 
 Message that will be shown if the input value is not a valid timezone.
 

docs/03x-rules-type.md

@@ -77,7 +77,7 @@ Available character type constraints:
 
 ### `message`
 
-type `string` default: `The {{ name }} value should be of type {{ constraint }}, {{ value }} given.`
+type: `string` default: `The {{ name }} value should be of type {{ constraint }}, {{ value }} given.`
 
 Message that will be shown if input value is not of a specific type.
 

src/ChainedValidatorInterface.php

@@ -33,6 +33,12 @@ public function eachValue(
         string $message = 'At key {{ key }}: {{ message }}'
     ): ChainedValidatorInterface&Validator;
 
+    static function email(
+        string $mode = 'html5',
+        ?callable $normalizer = null,
+        string $message = 'The {{ name }} value is not a valid email address, {{ value }} given.'
+    ): ChainedValidatorInterface&Validator;
+
     public function greaterThan(
         mixed $constraint,
         string $message = 'The {{ name }} value should be greater than {{ constraint }}, {{ value }} given.'

src/StaticValidatorInterface.php

@@ -32,6 +32,12 @@ public static function eachValue(
         string $message = 'At key {{ key }}: {{ message }}'
     ): ChainedValidatorInterface&Validator;
 
+    public static function email(
+        string $mode = 'html5',
+        ?callable $normalizer = null,
+        string $message = 'The {{ name }} value is not a valid email address, {{ value }} given.'
+    ): ChainedValidatorInterface&Validator;
+
     public static function greaterThan(
         mixed $constraint,
         string $message = 'The {{ name }} value should be greater than {{ constraint }}, {{ value }} given.'