[Validator] Fixed Traverse constraint reference

Author: HeahDude

reference/constraints/Traverse.rst

@@ -1,10 +1,10 @@
 Traverse
 ========
 
-Objects do not validate nested objects by default unless explicitly using
-this constraint.
-If only specific nested objects should be validated by cascade, consider
-using the :doc:`/reference/constraints/Valid` instead.
+Objects properties are only validated if they are accessible, either by being
+public or having public accessor methods (e.g a public getter).
+If your object needs to be traversed to validate its data, you can use this
+constraint.
 
 +----------------+-------------------------------------------------------------------------------------+
 | Applies to     | :ref:`class <validation-class-target>`                                              |
@@ -17,17 +17,14 @@ using the :doc:`/reference/constraints/Valid` instead.
 Basic Usage
 -----------
 
-In the following example, create three classes ``Book``, ``Author`` and
-``Editor`` that all have constraints on their properties. Furthermore,
-``Book`` stores an ``Author`` and an ``Editor`` instance that must be
-valid too. Instead of adding the ``Valid`` constraint to both fields,
-configure the ``Traverse`` constraint on the ``Book`` class.
+In the following example, create two classes ``BookCollection`` and ``Book``
+that all have constraints on their properties.
 
 .. configuration-block::
 
     .. code-block:: php-annotations
 
-        // src/AppBundle/Entity/Book.php
+        // src/AppBundle/Entity/BookCollection.php
         namespace AppBundle\Entity;
 
         use Doctrine\ORM\Mapping as ORM;
@@ -37,31 +34,66 @@ configure the ``Traverse`` constraint on the ``Book`` class.
          * @ORM\Entity
          * @Assert\Traverse
          */
-        class Book
+        class BookCollection implements \IteratorAggregate
         {
             /**
-             * @var Author
+             * @var string
+             *
+             * @ORM\Column
              *
-             * @ORM\ManyToOne(targetEntity="AppBundle\Entity\Author")
+             * @Assert\NotBlank
              */
-            protected $author;
+            protected $name = '';
 
             /**
-             * @var Editor
+             * @var Book[]
              *
-             * @ORM\ManyToOne(targetEntity="AppBundle\Entity\Editor")
+             * @ORM\ManyToMany(targetEntity="AppBundle\Entity\Book")
              */
-            protected $editor;
+            protected $books;
 
-            // ...
+            // some other properties
+
+            public function __construct()
+            {
+                $this->books = new ArrayCollection();
+            }
+
+            // ... setter for name, adder and remover for books
+
+            // the name can be validated by calling the getter
+            public function getName(): string
+            {
+                return $this->name;
+            }
+
+            /**
+             * @return Book[]|\Generator The books for a given author
+             */
+            public function getBooksForAuthor(Author $author): iterable
+            {
+                foreach ($this->books as $book) {
+                    if ($book->isAuthoredBy($author)) {
+                        yield $book;
+                    }
+                }
+            }
+
+            // neither the method above nor any other specific getter
+            // could be used to validated all nested books
+            // this object needs to be traversed to call the iterator
+            public function getIterator()
+            {
+                return $this->books->getIterator();
+            }
         }
 
     .. code-block:: yaml
 
         # src/AppBundle/Resources/config/validation.yml
-        AppBundle\Entity\Book:
+        AppBundle\Entity\BookCollection:
             constraints:
-                - Symfony\Component\Validator\Constraints\Traverse: ~
+                - Traverse: ~
 
     .. code-block:: xml
 
@@ -71,8 +103,8 @@ configure the ``Traverse`` constraint on the ``Book`` class.
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
-            <class name="AppBundle\Entity\Book">
-                <constraint name="Symfony\Component\Validator\Constraints\Traverse"/>
+            <class name="AppBundle\Entity\BookCollection">
+                <constraint name="Traverse"/>
             </class>
         </constraint-mapping>
 
@@ -84,15 +116,23 @@ configure the ``Traverse`` constraint on the ``Book`` class.
         use Symfony\Component\Validator\Constraints as Assert;
         use Symfony\Component\Validator\Mapping\ClassMetadata;
 
-        class Book
+        class BookCollection
         {
+            // ...
+
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addConstraint(new Assert\Traverse());
             }
         }
 
+If a public getter exists to return the inner books collection like
+``getBooks(): Collection``, the :doc:`/reference/constraints/Valid` constraint
+can be used on the ``$books`` property instead.
+
 Options
 -------
 
+The ``groups`` option is not available for this constraint.
+
 .. include:: /reference/constraints/_payload-option.rst.inc