Skip to content

Create "Formatted" validator #1657

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
henriquemoody wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Create "Formatted" validator #1657

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions docs/validators.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ In this page you will find a list of validators by their category.

**Date and Time**: [Date][] - [DateTime][] - [DateTimeDiff][] - [LeapDate][] - [LeapYear][] - [Time][]

**Display**: [Masked][] - [Named][] - [Templated][]
**Display**: [Formatted][] - [Masked][] - [Named][] - [Templated][]

**File system**: [Directory][] - [Executable][] - [Exists][] - [Extension][] - [File][] - [Image][] - [Mimetype][] - [Readable][] - [Size][] - [SymbolicLink][] - [Writable][]

Expand All @@ -51,7 +51,7 @@ In this page you will find a list of validators by their category.

**Structures**: [Attributes][] - [Key][] - [KeyExists][] - [KeyOptional][] - [KeySet][] - [Property][] - [PropertyExists][] - [PropertyOptional][]

**Transformations**: [All][] - [Call][] - [Each][] - [Length][] - [Max][] - [Min][] - [Size][]
**Transformations**: [All][] - [Call][] - [Each][] - [Formatted][] - [Length][] - [Max][] - [Min][] - [Size][]

**Types**: [ArrayType][] - [ArrayVal][] - [BoolType][] - [BoolVal][] - [CallableType][] - [Countable][] - [FloatType][] - [FloatVal][] - [IntType][] - [IntVal][] - [IterableType][] - [IterableVal][] - [NullType][] - [NumericVal][] - [ObjectType][] - [ResourceType][] - [ScalarVal][] - [StringType][] - [StringVal][]

Expand Down Expand Up @@ -116,6 +116,7 @@ In this page you will find a list of validators by their category.
- [Finite][] - `v::finite()->assert('10');`
- [FloatType][] - `v::floatType()->assert(1.5);`
- [FloatVal][] - `v::floatVal()->assert(1.5);`
- [Formatted][] - `v::formatted(f::mask('1-4'), v::email())->assert('foo@example.com');`
- [Graph][] - `v::graph()->assert('LKM@#$%4;');`
- [GreaterThan][] - `v::greaterThan(10)->assert(11);`
- [GreaterThanOrEqual][] - `v::intVal()->greaterThanOrEqual(10)->assert(10);`
Expand Down Expand Up @@ -272,6 +273,7 @@ In this page you will find a list of validators by their category.
[Finite]: validators/Finite.md "Validates if the input is a finite number."
[FloatType]: validators/FloatType.md "Validates whether the type of the input is float."
[FloatVal]: validators/FloatVal.md "Validate whether the input value is float."
[Formatted]: validators/Formatted.md "Decorates a validator to format input values in error messages while still validating the original input."
[Graph]: validators/Graph.md "Validates if all characters in the input are printable and actually creates"
[GreaterThan]: validators/GreaterThan.md "Validates whether the input is greater than a value."
[GreaterThanOrEqual]: validators/GreaterThanOrEqual.md "Validates whether the input is greater than or equal to a value."
Expand Down
52 changes: 52 additions & 0 deletions docs/validators/Formatted.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
<!--
SPDX-FileCopyrightText: (c) Respect Project Contributors
SPDX-License-Identifier: MIT
-->

# Formatted

- `Formatted(Formatter $formatter, Validator $validator)`

Decorates a validator to format input values in error messages while still validating the original input.

```php
use Respect\StringFormatter\FormatterBuilder as f;

v::formatted(f::mask('1-4'), v::email())->assert('foo@example.com');
// Validation passes successfully

v::formatted(f::mask('1-4'), v::email())->assert('not an email');
// → "****an email" must be a valid email address

v::formatted(f::pattern('#### #### #### ####'), v::creditCard())->assert('4111111111111111');
// Validation passes successfully

v::formatted(f::pattern('#### #### #### ####'), v::creditCard())->assert('1234123412341234');
// → "1234 1234 1234 1234" must be a valid credit card number
```

This validator is useful for displaying formatted values in error messages, making them more readable for end users. For example, showing credit card numbers with spaces or phone numbers with proper formatting.

It uses [respect/string-formatter](https://github.com/Respect/StringFormatter) as the underlying formatting engine. See the [StringFormatter documentation](https://github.com/Respect/StringFormatter) for available formatters.

## Behavior

The validator first ensures the input is a valid string using `StringVal`. If the input passes string validation, it validates the original input using the inner validator. The formatted version is only used for display in error messages.

## Categorization

- Display
- Transformations

## Changelog

| Version | Description |
| ------: | :---------- |
| 3.0.0 | Created |

## See Also

- [Call](Call.md)
- [Masked](Masked.md)
- [Named](Named.md)
- [Templated](Templated.md)
3 changes: 3 additions & 0 deletions src/Mixins/AllBuilder.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
namespace Respect\Validation\Mixins;

use DateTimeImmutable;
use Respect\StringFormatter\Formatter;
use Respect\Validation\Validator;

interface AllBuilder
Expand Down Expand Up @@ -132,6 +133,8 @@ public static function allFloatType(): Chain;

public static function allFloatVal(): Chain;

public static function allFormatted(Formatter $formatter, Validator $validator): Chain;

public static function allGraph(string ...$additionalChars): Chain;

public static function allGreaterThan(mixed $compareTo): Chain;
Expand Down
3 changes: 3 additions & 0 deletions src/Mixins/AllChain.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
namespace Respect\Validation\Mixins;

use DateTimeImmutable;
use Respect\StringFormatter\Formatter;
use Respect\Validation\Validator;

interface AllChain
Expand Down Expand Up @@ -132,6 +133,8 @@ public function allFloatType(): Chain;

public function allFloatVal(): Chain;

public function allFormatted(Formatter $formatter, Validator $validator): Chain;

public function allGraph(string ...$additionalChars): Chain;

public function allGreaterThan(mixed $compareTo): Chain;
Expand Down
3 changes: 3 additions & 0 deletions src/Mixins/Builder.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
namespace Respect\Validation\Mixins;

use DateTimeImmutable;
use Respect\StringFormatter\Formatter;
use Respect\Validation\Name;
use Respect\Validation\Validator;

Expand Down Expand Up @@ -139,6 +140,8 @@ public static function floatType(): Chain;

public static function floatVal(): Chain;

public static function formatted(Formatter $formatter, Validator $validator): Chain;

public static function graph(string ...$additionalChars): Chain;

public static function greaterThan(mixed $compareTo): Chain;
Expand Down
3 changes: 3 additions & 0 deletions src/Mixins/Chain.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
namespace Respect\Validation\Mixins;

use DateTimeImmutable;
use Respect\StringFormatter\Formatter;
use Respect\Validation\Name;
use Respect\Validation\Validator;
use Respect\Validation\ValidatorBuilder;
Expand Down Expand Up @@ -141,6 +142,8 @@ public function floatType(): Chain;

public function floatVal(): Chain;

public function formatted(Formatter $formatter, Validator $validator): Chain;

public function graph(string ...$additionalChars): Chain;

public function greaterThan(mixed $compareTo): Chain;
Expand Down
3 changes: 3 additions & 0 deletions src/Mixins/KeyBuilder.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
namespace Respect\Validation\Mixins;

use DateTimeImmutable;
use Respect\StringFormatter\Formatter;
use Respect\Validation\Validator;

interface KeyBuilder
Expand Down Expand Up @@ -134,6 +135,8 @@ public static function keyFloatType(int|string $key): Chain;

public static function keyFloatVal(int|string $key): Chain;

public static function keyFormatted(int|string $key, Formatter $formatter, Validator $validator): Chain;

public static function keyGraph(int|string $key, string ...$additionalChars): Chain;

public static function keyGreaterThan(int|string $key, mixed $compareTo): Chain;
Expand Down
3 changes: 3 additions & 0 deletions src/Mixins/KeyChain.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
namespace Respect\Validation\Mixins;

use DateTimeImmutable;
use Respect\StringFormatter\Formatter;
use Respect\Validation\Validator;

interface KeyChain
Expand Down Expand Up @@ -134,6 +135,8 @@ public function keyFloatType(int|string $key): Chain;

public function keyFloatVal(int|string $key): Chain;

public function keyFormatted(int|string $key, Formatter $formatter, Validator $validator): Chain;

public function keyGraph(int|string $key, string ...$additionalChars): Chain;

public function keyGreaterThan(int|string $key, mixed $compareTo): Chain;
Expand Down
3 changes: 3 additions & 0 deletions src/Mixins/NotBuilder.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
namespace Respect\Validation\Mixins;

use DateTimeImmutable;
use Respect\StringFormatter\Formatter;
use Respect\Validation\Validator;

interface NotBuilder
Expand Down Expand Up @@ -136,6 +137,8 @@ public static function notFloatType(): Chain;

public static function notFloatVal(): Chain;

public static function notFormatted(Formatter $formatter, Validator $validator): Chain;

public static function notGraph(string ...$additionalChars): Chain;

public static function notGreaterThan(mixed $compareTo): Chain;
Expand Down
3 changes: 3 additions & 0 deletions src/Mixins/NotChain.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
namespace Respect\Validation\Mixins;

use DateTimeImmutable;
use Respect\StringFormatter\Formatter;
use Respect\Validation\Validator;

interface NotChain
Expand Down Expand Up @@ -136,6 +137,8 @@ public function notFloatType(): Chain;

public function notFloatVal(): Chain;

public function notFormatted(Formatter $formatter, Validator $validator): Chain;

public function notGraph(string ...$additionalChars): Chain;

public function notGreaterThan(mixed $compareTo): Chain;
Expand Down
3 changes: 3 additions & 0 deletions src/Mixins/NullOrBuilder.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
namespace Respect\Validation\Mixins;

use DateTimeImmutable;
use Respect\StringFormatter\Formatter;
use Respect\Validation\Validator;

interface NullOrBuilder
Expand Down Expand Up @@ -136,6 +137,8 @@ public static function nullOrFloatType(): Chain;

public static function nullOrFloatVal(): Chain;

public static function nullOrFormatted(Formatter $formatter, Validator $validator): Chain;

public static function nullOrGraph(string ...$additionalChars): Chain;

public static function nullOrGreaterThan(mixed $compareTo): Chain;
Expand Down
3 changes: 3 additions & 0 deletions src/Mixins/NullOrChain.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
namespace Respect\Validation\Mixins;

use DateTimeImmutable;
use Respect\StringFormatter\Formatter;
use Respect\Validation\Validator;

interface NullOrChain
Expand Down Expand Up @@ -136,6 +137,8 @@ public function nullOrFloatType(): Chain;

public function nullOrFloatVal(): Chain;

public function nullOrFormatted(Formatter $formatter, Validator $validator): Chain;

public function nullOrGraph(string ...$additionalChars): Chain;

public function nullOrGreaterThan(mixed $compareTo): Chain;
Expand Down
3 changes: 3 additions & 0 deletions src/Mixins/PropertyBuilder.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
namespace Respect\Validation\Mixins;

use DateTimeImmutable;
use Respect\StringFormatter\Formatter;
use Respect\Validation\Validator;

interface PropertyBuilder
Expand Down Expand Up @@ -134,6 +135,8 @@ public static function propertyFloatType(string $propertyName): Chain;

public static function propertyFloatVal(string $propertyName): Chain;

public static function propertyFormatted(string $propertyName, Formatter $formatter, Validator $validator): Chain;

public static function propertyGraph(string $propertyName, string ...$additionalChars): Chain;

public static function propertyGreaterThan(string $propertyName, mixed $compareTo): Chain;
Expand Down
3 changes: 3 additions & 0 deletions src/Mixins/PropertyChain.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
namespace Respect\Validation\Mixins;

use DateTimeImmutable;
use Respect\StringFormatter\Formatter;
use Respect\Validation\Validator;

interface PropertyChain
Expand Down Expand Up @@ -134,6 +135,8 @@ public function propertyFloatType(string $propertyName): Chain;

public function propertyFloatVal(string $propertyName): Chain;

public function propertyFormatted(string $propertyName, Formatter $formatter, Validator $validator): Chain;

public function propertyGraph(string $propertyName, string ...$additionalChars): Chain;

public function propertyGreaterThan(string $propertyName, mixed $compareTo): Chain;
Expand Down
3 changes: 3 additions & 0 deletions src/Mixins/UndefOrBuilder.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
namespace Respect\Validation\Mixins;

use DateTimeImmutable;
use Respect\StringFormatter\Formatter;
use Respect\Validation\Validator;

interface UndefOrBuilder
Expand Down Expand Up @@ -134,6 +135,8 @@ public static function undefOrFloatType(): Chain;

public static function undefOrFloatVal(): Chain;

public static function undefOrFormatted(Formatter $formatter, Validator $validator): Chain;

public static function undefOrGraph(string ...$additionalChars): Chain;

public static function undefOrGreaterThan(mixed $compareTo): Chain;
Expand Down
3 changes: 3 additions & 0 deletions src/Mixins/UndefOrChain.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
namespace Respect\Validation\Mixins;

use DateTimeImmutable;
use Respect\StringFormatter\Formatter;
use Respect\Validation\Validator;

interface UndefOrChain
Expand Down Expand Up @@ -134,6 +135,8 @@ public function undefOrFloatType(): Chain;

public function undefOrFloatVal(): Chain;

public function undefOrFormatted(Formatter $formatter, Validator $validator): Chain;

public function undefOrGraph(string ...$additionalChars): Chain;

public function undefOrGreaterThan(mixed $compareTo): Chain;
Expand Down
42 changes: 42 additions & 0 deletions src/Validators/Formatted.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
<?php

/*
* SPDX-License-Identifier: MIT
* SPDX-FileCopyrightText: (c) Respect Project Contributors
* SPDX-FileContributor: Alexandre Gomes Gaigalas <alganet@gmail.com>
* SPDX-FileContributor: Danilo Benevides <danilobenevides01@gmail.com>
* SPDX-FileContributor: Graham Campbell <graham@mineuk.com>
* SPDX-FileContributor: Henrique Moody <henriquemoody@gmail.com>
* SPDX-FileContributor: Jayson Reis <santosdosreis@gmail.com>
* SPDX-FileContributor: Nick Lombard <github@jigsoft.co.za>
Comment on lines +6 to +11
Copy link
Member

@alganet alganet Jan 31, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see GitHub marking this file as newly added. Is this a moved file from somewhere else that GitHub didn't caught?

If it's a new file, perhaps we should review its FileContributor entries.

*/

declare(strict_types=1);

namespace Respect\Validation\Validators;

use Attribute;
use Respect\StringFormatter\Formatter;
use Respect\Validation\Result;
use Respect\Validation\Validator;

#[Attribute(Attribute::TARGET_PROPERTY | Attribute::IS_REPEATABLE)]
final readonly class Formatted implements Validator
{
public function __construct(
private Formatter $formatter,
private Validator $validator,
) {
}

public function evaluate(mixed $input): Result
{
$stringVal = new StringVal();
$stringValResult = $stringVal->evaluate($input);
if (!$stringValResult->hasPassed) {
return $stringValResult->withNameFrom($this->validator)->withIdFrom($this->validator);
}

return $this->validator->evaluate($input)->withInput($this->formatter->format((string) $input));
}
}
Loading