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

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.

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.

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.

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.

We should target 8.5, frankly.

For Symfony this would mean that we cannot easily implement the standard before version 9 which will be released in November 2027. That's quite a stretch.

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

proposed/validator.md

+ * Thrown ONLY if validator is misconfigured or cannot process request.
+ * MUST NOT be thrown if $value was actually tested, no matter the result.
+ */
+class ValidatorException extends \InvalidArgumentException


I believe FIG convention is to us an interface here to mark exceptions from this package, not a base class.

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

proposed/validator.md

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


Could also be a property.

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.

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.

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?

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

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

*

* @return string

*/

public function getMessage(): 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.

Could also be a property.

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


		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.

New PSR for standardizing Validator (ValidatorInterface) #1337

Are you sure you want to change the base?

New PSR for standardizing Validator (ValidatorInterface) #1337

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!

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

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!

Crell commented Jul 17, 2025

Uh oh!

Uh oh!

derrabus commented Jul 17, 2025 •

edited

Loading