Introduce Trimmed validator

This commit introduces the `Trimmed` validator that ensures a string
cannot start or end with a list of specific values.

The default values used are a selected list of Unicode invisible
characters.

To support this change, the StartsWith and EndsWith validators were
modified so they can also support multiple values to check for.

While StartsWith and EndsWith are more generic, and also perform
start-of-array and end-of-array kinds of checks, Trimmed is more
focused on string inputs, which tailors to a more specific use
case.

Author: alganet

docs/validators.md

@@ -49,7 +49,7 @@ In this page you will find a list of validators by their category.
 
 **Objects**: [Attributes][] - [Instance][] - [ObjectType][] - [Property][] - [PropertyExists][] - [PropertyOptional][]
 
-**Strings**: [Alnum][] - [Alpha][] - [Base64][] - [Charset][] - [Consonant][] - [Contains][] - [ContainsAny][] - [ContainsCount][] - [Control][] - [Digit][] - [Emoji][] - [EndsWith][] - [Format][] - [Graph][] - [HexRgbColor][] - [In][] - [Json][] - [Lowercase][] - [Phone][] - [PostalCode][] - [Printable][] - [Punct][] - [Regex][] - [Slug][] - [Sorted][] - [Space][] - [Spaced][] - [StartsWith][] - [StringType][] - [StringVal][] - [Uppercase][] - [Uuid][] - [Version][] - [Vowel][] - [Xdigit][]
+**Strings**: [Alnum][] - [Alpha][] - [Base64][] - [Charset][] - [Consonant][] - [Contains][] - [ContainsAny][] - [ContainsCount][] - [Control][] - [Digit][] - [Emoji][] - [EndsWith][] - [Format][] - [Graph][] - [HexRgbColor][] - [In][] - [Json][] - [Lowercase][] - [Phone][] - [PostalCode][] - [Printable][] - [Punct][] - [Regex][] - [Slug][] - [Sorted][] - [Space][] - [Spaced][] - [StartsWith][] - [StringType][] - [StringVal][] - [Trimmed][] - [Uppercase][] - [Uuid][] - [Version][] - [Vowel][] - [Xdigit][]
 
 **Structures**: [Attributes][] - [Key][] - [KeyExists][] - [KeyOptional][] - [KeySet][] - [Property][] - [PropertyExists][] - [PropertyOptional][]
 
@@ -203,6 +203,7 @@ In this page you will find a list of validators by their category.
 - [Templated][] - `v::templated('You must provide a valid email', v::email())->assert('foo@bar.com');`
 - [Time][] - `v::time()->assert('00:00:00');`
 - [Tld][] - `v::tld()->assert('com');`
+- [Trimmed][] - `v::trimmed()->assert('lorem ipsum');`
 - [TrueVal][] - `v::trueVal()->assert(true);`
 - [Undef][] - `v::undef()->assert('');`
 - [UndefOr][] - `v::undefOr(v::alpha())->assert('');`
@@ -351,7 +352,7 @@ In this page you will find a list of validators by their category.
 [Sorted]: validators/Sorted.md "Validates whether the input is sorted in a certain order or not."
 [Space]: validators/Space.md "Validates whether the input contains only whitespaces characters."
 [Spaced]: validators/Spaced.md "Validates if a string contains at least one whitespace (spaces, tabs, or line breaks);"
-[StartsWith]: validators/StartsWith.md "Validates whether the input starts with a given value."
+[StartsWith]: validators/StartsWith.md "Validates whether the input starts with one of the given values."
 [StringType]: validators/StringType.md "Validates whether the type of an input is string or not."
 [StringVal]: validators/StringVal.md "Validates whether the input can be used as a string."
 [SubdivisionCode]: validators/SubdivisionCode.md "Validates subdivision country codes according to ISO 3166-2."
@@ -360,6 +361,7 @@ In this page you will find a list of validators by their category.
 [Templated]: validators/Templated.md "Defines a validator with a custom message template."
 [Time]: validators/Time.md "Validates whether an input is a time or not. The `$format` argument should be in"
 [Tld]: validators/Tld.md "Validates whether the input is a top-level domain."
+[Trimmed]: validators/Trimmed.md "Validates whether the input string does not start or end with the given values."
 [TrueVal]: validators/TrueVal.md "Validates if a value is considered as `true`."
 [Undef]: validators/Undef.md "Validates if the given input is undefined. By _undefined_ we consider `null` or an empty string (`''`)."
 [UndefOr]: validators/UndefOr.md "Validates the input using a defined validator when the input is not `null` or an empty string (`''`)."

docs/validators/EndsWith.md

@@ -8,25 +8,32 @@ SPDX-FileContributor: Henrique Moody <henriquemoody@gmail.com>
 # EndsWith
 
 - `EndsWith(mixed $endValue)`
+- `EndsWith(mixed $endValue, mixed ...$endValues)`
 
 This validator is similar to `Contains()`, but validates
-only if the value is at the end of the input.
+only if one of the values is at the end of the input.
 
 For strings:
 
 ```php
 v::endsWith('ipsum')->assert('lorem ipsum');
 // Validation passes successfully
+
+v::endsWith('ipsum', 'dolor')->assert('lorem dolor');
+// Validation passes successfully
 ```
 
 For arrays:
 
 ```php
 v::endsWith('ipsum')->assert(['lorem', 'ipsum']);
 // Validation passes successfully
+
+v::endsWith('ipsum', 'dolor')->assert(['lorem', 'dolor']);
+// Validation passes successfully
 ```
 
-Message template for this validator includes `{{endValue}}`.
+Message template for this validator includes `{{endValue}}` and `{{endValues}}`.
 
 ## Templates
 
@@ -37,12 +44,20 @@ Message template for this validator includes `{{endValue}}`.
 |  `default` | {{subject}} must end with {{endValue}}     |
 | `inverted` | {{subject}} must not end with {{endValue}} |
 
+### `EndsWith::TEMPLATE_MULTIPLE_VALUES`
+
+|       Mode | Template                                                 |
+| ---------: | :------------------------------------------------------- |
+|  `default` | {{subject}} must end with {{endValues&#124;list:or}}     |
+| `inverted` | {{subject}} must not end with {{endValues&#124;list:or}} |
+
 ## Template placeholders
 
 | Placeholder | Description                                                      |
 | ----------- | ---------------------------------------------------------------- |
-| `endValue`  |                                                                  |
 | `subject`   | The validated input or the custom validator name (if specified). |
+| `endValue`  | The value that will be checked to be at the end of the input.    |
+| `endValues` | Additional values to check.                                      |
 
 ## Categorization
 
@@ -53,6 +68,7 @@ Message template for this validator includes `{{endValue}}`.
 
 | Version | Description                         |
 | ------: | :---------------------------------- |
+|   3.1.0 | Added support for multiple values   |
 |   3.0.0 | Case-insensitive comparison removed |
 |   0.3.9 | Created                             |
 
@@ -62,3 +78,4 @@ Message template for this validator includes `{{endValue}}`.
 - [In](In.md)
 - [Regex](Regex.md)
 - [StartsWith](StartsWith.md)
+- [Trimmed](Trimmed.md)

docs/validators/StartsWith.md

@@ -9,8 +9,9 @@ SPDX-FileContributor: Henrique Moody <henriquemoody@gmail.com>
 # StartsWith
 
 - `StartsWith(mixed $startValue)`
+- `StartsWith(mixed $startValue, mixed ...$startValues)`
 
-Validates whether the input starts with a given value.
+Validates whether the input starts with one of the given values.
 
 This validator is similar to [Contains](Contains.md), but validates only
 if the value is at the beginning of the input.
@@ -20,16 +21,22 @@ For strings:
 ```php
 v::startsWith('lorem')->assert('lorem ipsum');
 // Validation passes successfully
+
+v::startsWith('lorem', 'ipsum')->assert('ipsum dolor');
+// Validation passes successfully
 ```
 
 For arrays:
 
 ```php
 v::startsWith('lorem')->assert(['lorem', 'ipsum']);
 // Validation passes successfully
+
+v::startsWith('lorem', 'ipsum')->assert(['ipsum', 'dolor']);
+// Validation passes successfully
 ```
 
-Message template for this validator includes `{{startValue}}`.
+Message template for this validator includes `{{startValue}}` and `{{startValues}}`.
 
 ## Templates
 
@@ -40,12 +47,20 @@ Message template for this validator includes `{{startValue}}`.
 |  `default` | {{subject}} must start with {{startValue}}     |
 | `inverted` | {{subject}} must not start with {{startValue}} |
 
+### `StartsWith::TEMPLATE_MULTIPLE_VALUES`
+
+|       Mode | Template                                                     |
+| ---------: | :----------------------------------------------------------- |
+|  `default` | {{subject}} must start with {{startValues&#124;list:or}}     |
+| `inverted` | {{subject}} must not start with {{startValues&#124;list:or}} |
+
 ## Template placeholders
 
-| Placeholder  | Description                                                      |
-| ------------ | ---------------------------------------------------------------- |
-| `subject`    | The validated input or the custom validator name (if specified). |
-| `startValue` |                                                                  |
+| Placeholder   | Description                                                      |
+| ------------- | ---------------------------------------------------------------- |
+| `subject`     | The validated input or the custom validator name (if specified). |
+| `startValue`  | The value that will be checked to be at the start of the input.  |
+| `startValues` | Additional values to check.                                      |
 
 ## Categorization
 
@@ -56,6 +71,7 @@ Message template for this validator includes `{{startValue}}`.
 
 | Version | Description                         |
 | ------: | :---------------------------------- |
+|   3.1.0 | Added support for multiple values   |
 |   3.0.0 | Case-insensitive comparison removed |
 |   0.3.9 | Created                             |
 
@@ -65,3 +81,4 @@ Message template for this validator includes `{{startValue}}`.
 - [EndsWith](EndsWith.md)
 - [In](In.md)
 - [Regex](Regex.md)
+- [Trimmed](Trimmed.md)

docs/validators/Trimmed.md

@@ -0,0 +1,75 @@
+<!--
+SPDX-License-Identifier: MIT
+SPDX-FileCopyrightText: (c) Respect Project Contributors
+-->
+
+# Trimmed
+
+- `Trimmed()`
+- `Trimmed(string ...$trimValues)`
+
+Validates whether the input string does not start or end with the given values.
+
+When no values are provided, this validator uses a default list of Unicode invisible characters (including regular whitespace, non-breaking spaces, and zero-width characters).
+
+With the default values:
+
+```php
+v::trimmed()->assert('lorem ipsum');
+// Validation passes successfully
+
+v::trimmed()->assert("\u{200B}lorem");
+// → "​lorem" must be trimmed
+```
+
+With custom values:
+
+```php
+v::trimmed('foo', 'bar')->assert('bazqux');
+// Validation passes successfully
+
+v::trimmed('foo', 'bar')->assert('foobaz');
+// → "foobaz" must be trimmed of "foo" or "bar"
+```
+
+This validator composes [StartsWith](StartsWith.md) and [EndsWith](EndsWith.md).
+
+## Templates
+
+### `Trimmed::TEMPLATE_STANDARD`
+
+|       Mode | Template                        |
+| ---------: | :------------------------------ |
+|  `default` | {{subject}} must be trimmed     |
+| `inverted` | {{subject}} must not be trimmed |
+
+### `Trimmed::TEMPLATE_CUSTOM`
+
+|       Mode | Template                                                       |
+| ---------: | :------------------------------------------------------------- |
+|  `default` | {{subject}} must be trimmed of {{trimValues&#124;list:or}}     |
+| `inverted` | {{subject}} must not be trimmed of {{trimValues&#124;list:or}} |
+
+## Template placeholders
+
+| Placeholder  | Description                                                      |
+| ------------ | ---------------------------------------------------------------- |
+| `subject`    | The validated input or the custom validator name (if specified). |
+| `trimValues` |                                                                  |
+
+## Categorization
+
+- Strings
+
+## Changelog
+
+| Version | Description |
+| ------: | :---------- |
+|   3.1.0 | Created     |
+
+## See Also
+
+- [EndsWith](EndsWith.md)
+- [Space](Space.md)
+- [Spaced](Spaced.md)
+- [StartsWith](StartsWith.md)