Skip to content

New PSR for standardizing Validator (ValidatorInterface) #1337

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.

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
wants to merge 2 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
87 changes: 87 additions & 0 deletions proposed/validator-meta.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
Validator Meta Document
=======================

## 1. Summary

The SimpleValidatorInterface and ExtendedValidatorInterface define universal, minimalistic contracts for value validation in PHP. They provide a unified way to perform type-agnostic validations with either a simple pass/fail response (suitable for most form or field inputs) or a detailed, structured validation report, supporting error codes for i18n and advanced cases. Inspired by Symfony's Validator and `Respect\Validation`, these interfaces allow maximum interoperability and rapid provider/implementation swap, while enabling framework- and library-level integration without tight coupling.

Applications MAY depend only on these interfaces and swap implementations (or chains/compositions of validators) via DI, reducing coupling and simplifying maintenance, testing, and future migrations.

## 2. Why Bother?

Form and value validation is a ubiquitous problem across all PHP applications. Today, each framework (Symfony, Laravel, Yii, etc.) exposes its own interfaces, making it difficult to share validators, migrate between frameworks or libraries, or compose validation pipelines with userland tools.

A universal validator contract allows:

Rapid replacement of validation engines or libraries (vendor-agnostic interface).
Interchangeable custom and vendor-specific validators (e.g., open-source and proprietary).
Testability and integration with dependency injection containers.
Consistent error format for user feedback, translation, or error mapping.
Clean separation of simple (bool) and extended (structured, multi-error) validation.
This pattern avoids having to deeply couple code to a specific validator ecosystem (as in Symfony) and dramatically reduces refactoring when switching stacks or updating validation strategies.
Copy link
Contributor

Choose a reason for hiding this comment

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

It's not just about specific applications switching stacks. It's about me being able to use a validation routine in a stand-alone library and not care if it's going to be used with Symfony, Slim, or Laravel. Eg, in Serde I can just tell people "if you want fancier validation, go use PSR-Whatever and leave me alone." (Or integrate a PSR-Whatever bridge into Serde if I feel like it.)

Copy link
Author

Choose a reason for hiding this comment

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

Oh, yeah, I see your point. Tho, I'm struggling with exact words to put that point in them 😕
Feel free to rephrase that in a suggestion)))


#### Pros:

- Plug-and-play with any validator implementations (no hard dependency on a specific package)
- Extensible (vendors can add extra methods, but must comply with the common interface)
- Clean and decoupled design
- Advanced: error codes, rich violation objects

#### Cons:

- Slight abstraction overhead (vs. using one concrete implementation)
- Vendor- or application-specific error codes are not enforced by spec (but spec supports them)
- Contextual or cross-field validation must be built upon (not in base interfaces)

## 3. Design Decisions

### 3.1. Simple vs. Extended

To satisfy both lightweight and complex needs, two interfaces are provided:

- `SimpleValidatorInterface` — exposes only `isValid(mixed $value): bool`. Suitable for basic needs (is it a valid phone? email? int in range?...) and maximizing performance.
Copy link
Member

Choose a reason for hiding this comment

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

Is that running a single validation rule against the value? If so, I'd name it differently... like RuleInterface or something.

Copy link
Author

Choose a reason for hiding this comment

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

Well... That probably IS a Constraint (like Symfony's) 🤔
Shall it contain methods like getCondition() or smth like that then?

Copy link
Member

Choose a reason for hiding this comment

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

Maybe. That would be very useful if you want to replicate the same validation on the client side (mobile, SPA frontend) based on the rules used.

- `ExtendedValidatorInterface` — exposes `validate(mixed $value): ValidatorResponseInterface`, for structured results (validation status, errors, error codes/messages/etc.).
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
- `ExtendedValidatorInterface` — exposes `validate(mixed $value): ValidatorResponseInterface`, for structured results (validation status, errors, error codes/messages/etc.).
- `ValidatorInterface` — exposes `validate(mixed $value): ValidatorResponseInterface`, for structured results (validation status, errors, error codes/messages/etc.).

for the reason in https://github.com/php-fig/fig-standards/pull/1337/files#r2213153862

This separation enables applications to pick the level of detail they need. Many use cases will use only the simple interface.

### 3.2. ValidatorResponseInterface

A response from ExtendedValidatorInterface must expose:

- `isValid(): bool` — Was validation successful?
- `getViolations(): array<ViolationInterface>` — Why did it fail, with detailed error objects.

### 3.3. ViolationInterface

Every violation contains:

- Machine-readable code (for programmatic matching, i18n, etc.).
Copy link
Contributor

Choose a reason for hiding this comment

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

Disagree here. The class name is the machine-readable code. We don't need more opaque inconsistent strings.

Copy link
Member

Choose a reason for hiding this comment

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

@Crell class name doesn't work well for exposing it in APIs i.e. JavaScript or Android/iOS clients should not be dealing with PHP fully qualified class names.

Copy link
Author

Choose a reason for hiding this comment

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

Actually, I thought of some flag-like codes like those ones in json_encode() function (second argument)
But, yeah, class names are not good enough - for example, if you want to pass those violations to frontend

- Human-readable message (for fallback user feedback).
- Optionally: parameters for message templates, offending value, etc.
Spec only mandates code and message; implementations may extend.

### 3.4. Exception Handling

Validation failures (value rejected) are NOT exceptional: response returned with errors.

Exceptions are for implementation/configuration/usage errors — not for negative validation.

### 3.5. Swappability & DI

Core purpose — to make validation logic universally pluggable and reusable, in both applications and stand-alone
libraries, with no forced dependency on any particular framework or DI mechanism, and with zero need for code changes
when switching validator implementations.

### 3.6. Scope

Only single-value validation in scope; not object/collection/nested.
Copy link
Member

Choose a reason for hiding this comment

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

I'd ensure that these fall into the given interfaces well.

Copy link
Member

Choose a reason for hiding this comment

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

Also, in reality, single value validation without context is not enough.

Contextual validation may be layered by implementors using extensions.
Copy link
Contributor

Choose a reason for hiding this comment

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

We should think through what compound validation would look like. That should be included.

Copy link
Author

Choose a reason for hiding this comment

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

That will probably require some analogue of Constraints (like in Symfony), which may be just too much for this PSR. Not quite sure


## 4. People

### 4.1 Editor(s)

- TBA

### 4.2 Working Group members

- TBA
140 changes: 140 additions & 0 deletions proposed/validator.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,140 @@
Validator PSR: Specification Draft
==================================

This document describes common interfaces to validate values in PHP, in both simple and structured modes.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
interpreted as described in [RFC 2119][].

[RFC 2119]: http://tools.ietf.org/html/rfc2119

## 1. Specification

### 1.1. Definitions

- Validation: Process of checking if input value satisfies certain constraints (type, format, range, etc.).
- Violation: Individual reason why a value fails validation (error).
- Error Code: Machine-readable string/code for a validation failure, suitable for mapping, i18n or programmatic branching.

## 2. Interfaces

### 2.1. SimpleValidatorInterface

```php
namespace Psr\Validator;

/**
* Minimalistic validator interface.
*/
interface SimpleValidatorInterface
{
/**
* Validates supplied value.
* MUST return true if $value passes.
* MUST return false if $value fails.
* MUST NOT throw exceptions if $value fails.
* SHOULD throw ValidatorException if the Validator itself could not tell if the value passes or not (e.g. Validator misconfigured)
Copy link
Member

Choose a reason for hiding this comment

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

Should we use generic \RuntimeException for this case?

Copy link
Author

Choose a reason for hiding this comment

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

No, because this one is more specific. RuntimeException is basically anything, while package exceptions is described specifically to show that error occures somewhere inside this package functionality

Copy link
Member

Choose a reason for hiding this comment

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

If you're not going to handle it specifically, it doesn't make sense to make it specific.

*
* @param mixed $value
*
* @throws ValidatorException
*
* @return bool
*/
public function isValid(mixed $value): bool;
}
```

## 2.2. ExtendedValidatorInterface

```php
namespace Psr\Validator;

/**
* Extended validator interface returning structured response.
*/
interface ExtendedValidatorInterface
{
/**
* Validates supplied value and returns a ValidatorResponseInterface instance.
* MUST return ValidatorResponseInterface if $value was validated at all (with any result).
* MUST NOT throw exceptions if $value fails.
* SHOULD throw ValidatorException if the Validator itself could not tell if the value passes or not (e.g. Validator misconfigured)
*
* @param mixed $value
*
* @throws ValidatorException
*
* @return ValidatorResponseInterface
*/
public function validate(mixed $value): ValidatorResponseInterface;
Copy link
Contributor

Choose a reason for hiding this comment

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

If the validation passed, we don't need detailed information. We can likely short-circuit that to something like true|ValidatorErrorInterface or similar.

Copy link
Member

Choose a reason for hiding this comment

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

@Crell that would create more code handling it. Having a single return value works better in this case.

Copy link
Author

Choose a reason for hiding this comment

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

Totally agree with @samdark here. I faced this problem in WordPress once - a core function used to return true|WP_Error and if you checked that via if ($response) you always got true condition. So, eventually, they changed call from

if ( retrieve_password( $user->user_login ) )

to

if ( true === retrieve_password( $user->user_login ) )

Regarding your thread - just... Why? Why do we need to complicate output instead of simplifying it?

p.s. I'm not even speaking about that we might want to read some details that Validator might provide on succesful validate

Copy link
Member

Choose a reason for hiding this comment

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

Usually there's a context that matters, such as in the case when you need a password to be repeated exactly.

Copy link
Author

Choose a reason for hiding this comment

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

Suggested change
public function validate(mixed $value): ValidatorResponseInterface;
public function validate(mixed $value, array $context = []): ValidatorResponseInterface;

Probably?

Copy link
Member

@samdark samdark Jul 23, 2025

Choose a reason for hiding this comment

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

Yes. Either that or a DTO.

}
```

## 2.3. ValidatorResponseInterface

```php
namespace Psr\Validator;

/**
* Wraps the result of validation including status and violations list.
*/
interface ValidatorResponseInterface
{
/**
* MUST return true if $value passed, and false otherwise.
* MUST be immutable.
*
* @return bool
*/
public function isValid(): bool;
Copy link
Contributor

Choose a reason for hiding this comment

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

This can be a property now, not a method. 😄

Copy link
Member

Choose a reason for hiding this comment

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

There are zero benefits making it a property. Just drawbacks.

Ie. If it is a property you are forcing the implementation to be a value object.

Choose a reason for hiding this comment

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

Those drawbacks should be gone with PHP 8.4 though. Not sure if we want to target PHP 8.4 for this standard just to gain access to hooked properties. That would as of today be rather strict and hurt the adoption of the standard.

Copy link
Member

Choose a reason for hiding this comment

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

But there are still no benefits... =)

Copy link
Contributor

Choose a reason for hiding this comment

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

  1. No, it does not force it to be a value object. It just changes the spelling to be simpler and more concise.
  2. The benefit is conceptual integrity. See the talk I gave at PHPTek this year on the new world properties open up for us.
  3. We should target 8.5, frankly. This wouldn't be ready before 8.5 is released anyway, and we've learned our lesson in the past that targeting an older-than-latest release always backfires and just makes more work for all involved.

Copy link
Contributor

Choose a reason for hiding this comment

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

Putting on my Core Committee hat for a moment, I will never vote for a spec that goes out of its way to support 10 year old versions of PHP. A spec will always be used far more in the future than in the past. Anyone on PHP 5 still (god help them) isn't going to be able to use any 3rd party validator libraries anyway, because those will all be written for more modern PHP versions.

We learned our lesson from PSR-6, and PSR-7 (if my memory of the timing is right). And did it right in PSR-14 by using object. Use whatever language features are current and useful. If that makes the PHP version requirement high, so be it. The future is longer than the past.

Choose a reason for hiding this comment

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

You are absolutely right @Crell about supporting ancient PHP releases. Most validation libraries that could adopt the new standard don't deliver new feature releases with PHP 7 support, so why bother about PHP 7.

But not supporting 10 year old PHP does not mean we have to exclude last year's PHP. As far as I can tell, requiring PHP 8.5 does not unlock any features that we could make use of in this contract, does it?

If hooked properties is what we want for this contract, let's target PHP 8.4? For Symfony at least, that would make adopting the standard way easier because we'll bump our PHP requirement to 8.4 in November.

Copy link
Contributor

Choose a reason for hiding this comment

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

If there's no 8.5 features that would be useful, then yes, a version target of 8.4 is fine. But if we do find there are 8.5 features that would be useful, we should be very open to then requiring 8.5 to use them.

Off hand, I can't think of any new 8.5 features that would be useful here, but interface properties from 8.4, definitely are useful.

Copy link
Author

@LeTraceurSnork LeTraceurSnork Jul 22, 2025

Choose a reason for hiding this comment

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

I would've understand if you'd say smth like we can't support PHP 5.6 because we need to use object type as param (which we don't...yet). But drop older versions support just because 8.5 is fancy? Why? It's not like we need to do something overbearing - just not use new syntax in an interface (that may be used, btw, in libraries that extends that interface). It's not like interface suggests usage of money_format() or smth 😁

Copy link
Member

Choose a reason for hiding this comment

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

I think this long discussion proves my point.

There are zero benefits making it a property. Just drawbacks.

I understand we have property hooks and interface properties in PHP 8.4. But these two features did not bring any value to PHP other then "it is nicer to write".

Since a PSR should be a standardized way to do something, I think we should consider adoption rather than try to move libraries to use language features that does not give any value.

My strongest recommendation is to keep these as methods.


/**
* Returns all violations (validation errors) as ViolationInterface objects.
*
* @return ViolationInterface[]
*/
public function getViolations(): array;
}
```

## 2.4. ViolationInterface

```php
namespace Psr\Validator;

/**
* A single validation violation.
*/
interface ViolationInterface
Copy link
Member

Choose a reason for hiding this comment

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

For intl, there is a need for:

 /**
     * Returns parameters used for {@see $message} translation.
     *
     * @return array A mapping between parameter names and values.
     */
    public function getParameters(): array

{
/**
* Machine-readable error code (for mapping, i18n, client logic).
*
* @return string
*/
public function getCode(): string;
Copy link
Contributor

Choose a reason for hiding this comment

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

As specified, this is extraneous and unhelpful.


/**
* Error message (human-readable, MAY be locale-dependent).
*
* @return string
*/
public function getMessage(): string;
Copy link
Contributor

Choose a reason for hiding this comment

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

Could also be a property.

Copy link
Author

Choose a reason for hiding this comment

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

I suggest we decide that in one thread and then apply to all
#1337 (comment)

}
```

## 2.5. ValidatorException

```php
namespace Psr\Validator;

/**
* Thrown ONLY if validator is misconfigured or cannot process request.
* MUST NOT be thrown if $value was actually tested, no matter the result.
*/
interface ValidatorException
{
}
```