New PSR for standardizing Validator (ValidatorInterface) #1337

LeTraceurSnork · 2025-07-16T14:53:38Z

Here's a proposal of new PSR for standardizing Validators to one interface
Continuation of long-lasting discussions on official Discord channel

Goal

To unite ~~earth and water~~ many separated validator libraries under one interface so the switching and DI would be easier, protect from potential vendor-locks and reduce coupling.

LeTraceurSnork · 2025-07-16T14:57:00Z

@Crell @KorvinSzanto I guess you would want to at least look at it
@fabpot and I would appreciate your opinion as well, given that I based this on Symfony's validators xD

Crell · 2025-07-16T16:12:42Z

proposed/validator-meta.md

+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.


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.)

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)))

Crell · 2025-07-16T16:14:36Z

proposed/validator-meta.md

+
+Every violation contains:
+
+- Machine-readable code (for programmatic matching, i18n, etc.). 


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

@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.

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

Crell · 2025-07-16T16:15:10Z

proposed/validator-meta.md

+
+### 3.5. Swappability & DI
+
+Core purpose — to allow hot-swapping validator engines and compositions via DI or configuration, zero code refactor.


Crell · 2025-07-16T16:15:56Z

proposed/validator-meta.md

+### 3.6. Scope
+
+Only single-value validation in scope; not object/collection/nested.
+Contextual validation may be layered by implementors using extensions.


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

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

Crell · 2025-07-16T16:16:21Z

proposed/validator.md

+The final implementations MAY decorate the objects with more
+functionality than the one proposed but they MUST implement the indicated
+interfaces/functionality first.


This block is unnecessary.

Crell · 2025-07-16T16:17:58Z

proposed/validator.md

+     *
+     * @return ValidatorResponseInterface
+     */
+    public function validate(mixed $value): ValidatorResponseInterface;


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

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

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

Crell · 2025-07-16T16:18:32Z

proposed/validator.md

+     *
+     * @return bool
+     */
+    public function isValid(): bool;


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

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.

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.

But there are still no benefits... =)

No, it does not force it to be a value object. It just changes the spelling to be simpler and more concise.

The benefit is conceptual integrity. See the talk I gave at PHPTek this year on the new world properties open up for us.

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.

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.

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.

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.

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 😁

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.

proposed/validator.md

Crell · 2025-07-16T16:19:45Z

proposed/validator.md

+     *
+     * @return string
+     */
+    public function getMessage(): string;


Could also be a property.

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

Crell · 2025-07-16T16:19:56Z

proposed/validator.md

+     *
+     * @return string
+     */
+    public function getCode(): string;


As specified, this is extraneous and unhelpful.

Crell · 2025-07-16T16:20:23Z

As I have said many times, get the WG together first, design details second. 😄

Crell · 2025-07-16T16:22:02Z

Also: The current proposal doesn't seem to go far enough. How do I link the validator to metadata? Would, for instance, an attribute implement this interface? If so, what does it do if it needs a service to do its validation? (Eg, "does this record exist in the db?") Then the validation metdata (attribute) and the validation logic (a service) need to be separate.

We don't have to mandate how that is handled, but we do need to ensure that it can be handled in a clean and portable fashion.

derrabus · 2025-07-17T07:37:15Z

Hello and thank you for working on this proposal. I believe and common interface for validators can be useful, especially for interoperability with libraries and even external systems like JS frontends. A few remarks from my side. I'll might add some more later when I have more time.

Source of violation

Why I validate a complex object, a violation with a human-readable message is often not enough. Imagine, the object represents a form submitted by the user. I want to validate the whole object and receive a list of violations. If the form is invalid, I want to render the message next to the field with the invalid input. In order to facilitate that, I need a machine readable representation of the property path. This is how Symfony does it.

https://github.com/symfony/symfony/blob/5015234dd9fe86dee561eb31a0de524f68a052a0/src/Symfony/Component/Validator/ConstraintViolationInterface.php#L86-L98

I'm not saying you should copy the way Symfony does it, but please take that use-case into consideration.

Translation

Regarding the error message, you're documenting it as…

Error message (human-readable, MAY be locale-dependent).

This basically means that the validator has to be aware of the target locale when conducting the validation. This also means that I can only target a single locale which I have to determine before calling the validator. It would be great if the violation object would be translatable in some way. Unfortunately, we don't have a PSR standard for translators or translatable objects.

samdark

Overall, I see it an interesting thing to standardize. Here's what we have in Yii3 about the topic:

https://github.com/yiisoft/validator

samdark · 2025-07-17T12:03:04Z

proposed/validator-meta.md

+
+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. 


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

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

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.

samdark · 2025-07-17T12:03:44Z

proposed/validator-meta.md

+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. 
+- `ExtendedValidatorInterface` — exposes `validate(mixed $value): ValidatorResponseInterface`, for structured results (validation status, errors, error codes/messages/etc.).


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

samdark · 2025-07-17T12:05:17Z

proposed/validator-meta.md

+
+Every violation contains:
+
+- Machine-readable code (for programmatic matching, i18n, etc.). 


@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.

samdark · 2025-07-17T12:18:18Z

proposed/validator-meta.md

+
+### 3.6. Scope
+
+Only single-value validation in scope; not object/collection/nested.


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

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

samdark · 2025-07-17T12:21:31Z

proposed/validator.md

+     *
+     * @return ValidatorResponseInterface
+     */
+    public function validate(mixed $value): ValidatorResponseInterface;


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

Suggested change

public function validate(mixed $value): ValidatorResponseInterface;

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

Probably?

Yes. Either that or a DTO.

samdark · 2025-07-17T12:26:18Z

proposed/validator.md

+     * 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)


Should we use generic \RuntimeException for this case?

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

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

samdark · 2025-07-17T12:36:18Z

proposed/validator.md

+     *
+     * @return ValidatorResponseInterface
+     */
+    public function validate(mixed $value): ValidatorResponseInterface;


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

samdark · 2025-07-17T12:38:58Z

proposed/validator.md

+/**
+ * A single validation violation.
+ */
+interface ViolationInterface


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

Crell · 2025-07-17T14:36:11Z

@samdark Please don't use "Reviews". They break threading badly. 😄

Having a single ValidatorResponseInterface on which you have to check isValid is also more code. There will be code that determines which validators passed and which failed either way. The rest is just spelling. And for spelling, I (almost) always favor using the type system.

Re using the class name as the ID: The ID is an opaque string currently. It wouldn't be useful to some other system anyway. Honestly I'm not even sure what purpose it serves to exist at all, so unless that can be demonstrated I would object to having it. (Not something that has to be resolved before a WG forms, of course. The WG vote should likely include a lot fewer details than what is listed here.)

samdark · 2025-07-23T10:36:25Z

@Crell That's what I've used to... and these give a very good context cause comments are attached to certain code.

New PSR for standardizing Validator (ValidatorInterface)

3bfe67d

LeTraceurSnork requested a review from a team as a code owner July 16, 2025 14:53

Crell reviewed Jul 16, 2025

View reviewed changes

proposed/validator.md Outdated Show resolved Hide resolved

Crell reviewed Jul 16, 2025

View reviewed changes

proposed/validator.md

*

* @return string

*/

public function getCode(): string;

Copy link

Contributor

Crell Jul 16, 2025

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.

samdark reviewed Jul 17, 2025

View reviewed changes

docs: Swappability & DI clarified, Exception now interface

6284964


		Every violation contains:

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


		### 3.5. Swappability & DI

		Core purpose — to allow hot-swapping validator engines and compositions via DI or configuration, zero code refactor.


		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.

	- `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.).


		### 3.6. Scope

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

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

New PSR for standardizing Validator (ValidatorInterface) #1337

Are you sure you want to change the base?

New PSR for standardizing Validator (ValidatorInterface) #1337

Uh oh!

Conversation

LeTraceurSnork commented Jul 16, 2025

Goal

Uh oh!

LeTraceurSnork commented Jul 16, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LeTraceurSnork Jul 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Crell commented Jul 16, 2025

Uh oh!

Crell commented Jul 16, 2025

Uh oh!

derrabus commented Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Source of violation

Translation

Uh oh!

samdark left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

LeTraceurSnork Jul 22, 2025 •

edited

Loading

derrabus commented Jul 17, 2025 •

edited

Loading

samdark Jul 23, 2025 •

edited

Loading