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('[email protected]'); // true
+Validator::email()->validate('test@example'); // false
+
+// html5-allow-no-tld mode
+Validator::email(mode: 'html5-allow-no-tld')->validate('[email protected]'); // 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('[email protected] '); // false
+
+Validator::email(normalizer: 'trim')->validate('[email protected] '); // true
+Validator::email(normalizer: fn($value) => trim($value))->validate('[email protected] '); // 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);
+    }
+}

src/Exception/UnexpectedTypeException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace ProgrammatorDev\YetAnotherPhpValidator\Exception;
+
+class UnexpectedTypeException extends UnexpectedValueException
+{
+    public function __construct(string $expected, string $given)
+    {
+        $message = \sprintf('Expected value of type "%s", "%s" given.', $expected, $given);
+
+        parent::__construct($message);
+    }
+}

src/Rule/Choice.php

@@ -3,6 +3,7 @@
 namespace ProgrammatorDev\YetAnotherPhpValidator\Rule;
 
 use ProgrammatorDev\YetAnotherPhpValidator\Exception\ChoiceException;
+use ProgrammatorDev\YetAnotherPhpValidator\Exception\UnexpectedTypeException;
 use ProgrammatorDev\YetAnotherPhpValidator\Exception\UnexpectedValueException;
 
 class Choice extends AbstractRule implements RuleInterface
@@ -21,9 +22,7 @@ public function __construct(
     public function assert(mixed $value, ?string $name = null): void
     {
         if ($this->multiple && !\is_array($value)) {
-            throw new UnexpectedValueException(
-                \sprintf('Expected value of type "array" when using multiple choices, "%s" given', get_debug_type($value))
-            );
+            throw new UnexpectedTypeException('array', get_debug_type($value));
         }
 
         if (

src/Rule/Country.php

@@ -3,7 +3,8 @@
 namespace ProgrammatorDev\YetAnotherPhpValidator\Rule;
 
 use ProgrammatorDev\YetAnotherPhpValidator\Exception\CountryException;
-use ProgrammatorDev\YetAnotherPhpValidator\Exception\UnexpectedValueException;
+use ProgrammatorDev\YetAnotherPhpValidator\Exception\UnexpectedOptionException;
+use ProgrammatorDev\YetAnotherPhpValidator\Exception\UnexpectedTypeException;
 use Symfony\Component\Intl\Countries;
 
 class Country extends AbstractRule implements RuleInterface
@@ -24,19 +25,11 @@ public function __construct(
     public function assert(mixed $value, ?string $name = null): void
     {
         if (!\in_array($this->code, self::CODE_OPTIONS)) {
-            throw new UnexpectedValueException(
-                \sprintf(
-                    'Invalid code "%s". Accepted values are: "%s".',
-                    $this->code,
-                    \implode(", ", self::CODE_OPTIONS)
-                )
-            );
+            throw new UnexpectedOptionException('code', self::CODE_OPTIONS, $this->code);
         }
 
         if (!\is_string($value)) {
-            throw new UnexpectedValueException(
-                \sprintf('Expected value of type "string", "%s" given.', get_debug_type($value))
-            );
+            throw new UnexpectedTypeException('string', get_debug_type($value));
         }
 
         // Keep original value for parameters

src/Rule/EachKey.php

@@ -3,7 +3,7 @@
 namespace ProgrammatorDev\YetAnotherPhpValidator\Rule;
 
 use ProgrammatorDev\YetAnotherPhpValidator\Exception\EachKeyException;
-use ProgrammatorDev\YetAnotherPhpValidator\Exception\UnexpectedValueException;
+use ProgrammatorDev\YetAnotherPhpValidator\Exception\UnexpectedTypeException;
 use ProgrammatorDev\YetAnotherPhpValidator\Exception\ValidationException;
 use ProgrammatorDev\YetAnotherPhpValidator\Validator;
 
@@ -17,9 +17,7 @@ public function __construct(
     public function assert(mixed $value, ?string $name = null): void
     {
         if (!\is_iterable($value)) {
-            throw new UnexpectedValueException(
-                \sprintf('Expected value of type "array|\Traversable", "%s" given.', get_debug_type($value))
-            );
+            throw new UnexpectedTypeException('array|\Traversable', get_debug_type($value));
         }
 
         try {

src/Rule/EachValue.php

@@ -3,7 +3,7 @@
 namespace ProgrammatorDev\YetAnotherPhpValidator\Rule;
 
 use ProgrammatorDev\YetAnotherPhpValidator\Exception\EachValueException;
-use ProgrammatorDev\YetAnotherPhpValidator\Exception\UnexpectedValueException;
+use ProgrammatorDev\YetAnotherPhpValidator\Exception\UnexpectedTypeException;
 use ProgrammatorDev\YetAnotherPhpValidator\Exception\ValidationException;
 use ProgrammatorDev\YetAnotherPhpValidator\Validator;
 
@@ -17,9 +17,7 @@ public function __construct(
     public function assert(mixed $value, ?string $name = null): void
     {
         if (!\is_iterable($value)) {
-            throw new UnexpectedValueException(
-                \sprintf('Expected value of type "array|\Traversable", "%s" given.', get_debug_type($value))
-            );
+            throw new UnexpectedTypeException('array|\Traversable', get_debug_type($value));
         }
 
         try {

src/Rule/Email.php

@@ -0,0 +1,79 @@
+<?php
+
+namespace ProgrammatorDev\YetAnotherPhpValidator\Rule;
+
+use Egulias\EmailValidator\EmailValidator;
+use Egulias\EmailValidator\Validation\NoRFCWarningsValidation;
+use ProgrammatorDev\YetAnotherPhpValidator\Exception\EmailException;
+use ProgrammatorDev\YetAnotherPhpValidator\Exception\UnexpectedOptionException;
+use ProgrammatorDev\YetAnotherPhpValidator\Exception\UnexpectedTypeException;
+
+class Email extends AbstractRule implements RuleInterface
+{
+    public const MODE_HTML5 = 'html5';
+    public const MODE_HTML5_ALLOW_NO_TLD = 'html5-allow-no-tld';
+    public const MODE_STRICT = 'strict';
+
+    private const EMAIL_MODES = [
+        self::MODE_HTML5,
+        self::MODE_HTML5_ALLOW_NO_TLD,
+        self::MODE_STRICT
+    ];
+
+    private const EMAIL_PATTERNS = [
+        self::MODE_HTML5 => '/^[a-zA-Z0-9.!#$%&\'*+\\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+$/',
+        self::MODE_HTML5_ALLOW_NO_TLD => '/^[a-zA-Z0-9.!#$%&\'*+\\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/'
+    ];
+
+    // Using array to bypass unallowed callable type in properties
+    private array $normalizer;
+
+    public function __construct(
+        private readonly string $mode = self::MODE_HTML5,
+        ?callable $normalizer = null,
+        private readonly string $message = 'The {{ name }} value is not a valid email address, {{ value }} given.'
+    )
+    {
+        $this->normalizer['callable'] = $normalizer;
+    }
+
+    public function assert(mixed $value, ?string $name = null): void
+    {
+        if (!\in_array($this->mode, self::EMAIL_MODES, true)) {
+            throw new UnexpectedOptionException('mode', self::EMAIL_MODES, $this->mode);
+        }
+
+        if (!\is_string($value)) {
+            throw new UnexpectedTypeException('string', get_debug_type($value));
+        }
+
+        if ($this->normalizer['callable'] !== null) {
+            $value = ($this->normalizer['callable'])($value);
+        }
+
+        if ($this->mode === self::MODE_STRICT) {
+            $emailValidator = new EmailValidator();
+
+            if (!$emailValidator->isValid($value, new NoRFCWarningsValidation())) {
+                throw new EmailException(
+                    message: $this->message,
+                    parameters: [
+                        'value' => $value,
+                        'name' => $name,
+                        'mode' => $this->mode
+                    ]
+                );
+            }
+        }
+        else if (!\preg_match(self::EMAIL_PATTERNS[$this->mode], $value)) {
+            throw new EmailException(
+                message: $this->message,
+                parameters: [
+                    'value' => $value,
+                    'name' => $name,
+                    'mode' => $this->mode
+                ]
+            );
+        }
+    }
+}