[Validator] `When()` constraint documentation misleading ?

[alcohol]

I am calling $validator->validate($object, [ /* Constraint[] */ ]) . One of the constraints is a When constraint. But inside the expression, this is not an object neither is context.getObject() - I would have expected both to refer to $object 🤔

However, I guess it is because I am validating an object as if it were a raw value, as documented on https://symfony.com/doc/current/validation/raw_values.html - rather than having the constraints tied to the object (that is because I am validating the same object against multiple groups of constraints defined by other objects).

It took me a while to realize, that the following information is misleading or simply not true in my scenario:

https://symfony.com/doc/current/reference/constraints/When.html#expression

value
The value of the property being validated (only available when the constraint is applied to a property).

This is not true in my case, since the object is the 'raw' value, value is actually the object here (not a property).

Should the documentation be adjusted somehow to better clarify this?

[stof]

value is always the value on which the constraint is applied. It is always available.

When using When as a class-level constraint, the value will be the object instance. And when validating dedicated constraints (rather than validating an object based on its mapped constraint), it is the value passed to the validator.

Do you want to help improving this documentation by sending a PR ?

[alcohol]

I wanted to be sure my thoughts were correct before submitting a PR. How could we best clarify this distinction; do you have a suggestion?

Merely changing the description of what value represents? Or a completely different paragraph that highlights the distinction between validating objects with class/property level constraints vs. raw value validation?

[stof]

I would improve the description of value

[alcohol]

Am I correct in understanding that the current description was even more wrong than I assumed; as in - value is the same as this when the constraint is applied on a class rather than a property?

[stof]

@alcohol indeed. For class-level constraints, both value and this are referring to the validated object (for different reasons).

And when passing explicit constraints to the validate call, the value of this is the existing value in the context where this was called (which might be null if there is no such context).

[javiereguiluz]

Closed by #21191.