Merge pull request #48 from programmatordev/1.x

1.x

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,11 @@
 - [NotBlank](03x-rules-not-blank.md)
 - [Type](03x-rules-type.md)
 
+## String Rules
+
+- [Email](03x-rules-email.md)
+- [URL](03x-rules-url.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`.
 
@@ -136,4 +136,8 @@ The following parameters are available:
 | `{{ name }}`          | Name of the invalid value            |
 | `{{ constraints }}`   | The array of valid choices           |
 | `{{ minConstraint }}` | The minimum number of valid choices  |
-| `{{ maxConstraint }}` | The maximum number of valid choices  |
+| `{{ maxConstraint }}` | The maximum number of valid choices  |
+
+## Changelog
+
+- `0.1.0` Created

docs/03x-rules-country.md

@@ -52,4 +52,8 @@ The following parameters are available:
 |---------------|---------------------------|
 | `{{ value }}` | The current invalid value |
 | `{{ name }}`  | Name of the invalid value |
-| `{{ code }}`  | Selected code type        |
+| `{{ code }}`  | Selected code type        |
+
+## Changelog
+
+- `0.2.0` Created

docs/03x-rules-each-key.md

@@ -46,4 +46,8 @@ The following parameters are available:
 | `{{ name }}`    | Name of the invalid value                        |
 | `{{ key }}`     | The key of the invalid iterable element          |
 | `{{ element }}` | The value of the invalid iterable element        |
-| `{{ message }}` | The rule message of the invalid iterable element |
+| `{{ message }}` | The rule message of the invalid iterable element |
+
+## Changelog
+
+- `0.4.0` Created

docs/03x-rules-each-value.md

@@ -46,4 +46,8 @@ The following parameters are available:
 | `{{ name }}`    | Name of the invalid value                        |
 | `{{ key }}`     | The key of the invalid iterable element          |
 | `{{ element }}` | The value of the invalid iterable element        |
-| `{{ message }}` | The rule message of the invalid iterable element |
+| `{{ message }}` | The rule message of the invalid iterable element |
+
+## Changelog
+
+- `0.4.0` Created

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-greater-than-or-equal.md

@@ -54,4 +54,8 @@ The following parameters are available:
 |--------------------|---------------------------|
 | `{{ value }}`      | The current invalid value |
 | `{{ name }}`       | Name of the invalid value |
-| `{{ constraint }}` | The comparison value      |
+| `{{ constraint }}` | The comparison value      |
+
+## Changelog
+
+- `0.1.0` Created

docs/03x-rules-greater-than.md

@@ -54,4 +54,8 @@ The following parameters are available:
 |--------------------|---------------------------|
 | `{{ value }}`      | The current invalid value |
 | `{{ name }}`       | Name of the invalid value |
-| `{{ constraint }}` | The comparison value      |
+| `{{ constraint }}` | The comparison value      |
+
+## Changelog
+
+- `0.1.0` Created