Document how to validate associations

[webmozart]

There is currently little to no prose documentation about validating associations (apart from the Valid reference docs), both in the Validator documentation and in the Form documentation.

The Validator documentation should mention that cascaded validation needs to be activated actively for the associations of an object:

Annotations:

/**
 * @Assert\Valid
 */
private $author;

YAML:

properties:
    author:
        - Valid: ~

XML:

<property name="author">
    <constraint name="Valid" />
</property>

When applied to traversable relations (i.e. an array or a collection object), the relation will be traversed by default. Each object in the collection will be validated as well. This can be deactivated by setting the "traverse" option to false.

Deep traversal (e.g. in multi-level arrays) can be enabled by setting the "deep" option to true.

If you don't want to constrain a relationship with "Valid", but still validate the related object in the Form component, you can set the "cascade_validation" option to true on the root form:

$resolver->setDefaults(array(
    'cascade_validation' => true,
));

Constraints set using the "constraints" option will always be validated for nested forms, regardless of the "cascade_validation" setting.

[wouterj]

There is now a little bit more, the deep and cascade_validation options are now documented. However, we still need to add a little section in book/validation about validating referenced entities with the Valid constraint and then link to the reference docs.

[peterrehm]

Hence @webmozart's intention if deprecating cascade_validation I would be in favor of explaining only the Assert\Valid() more in detail to guide users already in the right direction.

[javiereguiluz]

I'm closing this as fixed because we've improved the Valid docs and we recently documented Traverse too (see #11310).