Merge pull request #46 from programmatordev/YAPV-19-create-email-rule

Create Email rule

Author: andrepimpao

.gitignore

@@ -5,4 +5,5 @@
 /vendor/
 /logs/
 /.idea
+/.ddev
 /index.php

composer.json

@@ -13,6 +13,7 @@
     ],
     "require": {
         "php": ">=8.1",
+        "egulias/email-validator": "^4.0",
         "symfony/intl": "^6.3",
         "symfony/polyfill-ctype": "^1.27"
     },

docs/03-rules.md

@@ -1,6 +1,7 @@
 # Rules
 
 - [Basic Rules](#basic-rules)
+- [String Rules](#string-rules)
 - [Comparison Rules](#comparison-rules)
 - [Date Rules](#date-rules)
 - [Choice Rules](#choice-rules)
@@ -11,6 +12,10 @@
 - [NotBlank](03x-rules-not-blank.md)
 - [Type](03x-rules-type.md)
 
+## String Rules
+
+- [Email](03x-rules-email.md)
+
 ## Comparison Rules
 
 - [GreaterThan](03x-rules-greater-than.md)

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/Exception/EmailException.php

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

src/Exception/UnexpectedOptionException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace ProgrammatorDev\YetAnotherPhpValidator\Exception;
+
+class UnexpectedOptionException extends UnexpectedValueException
+{
+    public function __construct(string $name, array $expected, string $given)
+    {
+        $message = \sprintf('Invalid %s "%s". Accepted values are: "%s".', $name, $given, \implode('", "', $expected));
+
+        parent::__construct($message);
+    }
+}