Skip to content

Commit 822fe47

Browse files
webmozartwebmozart
committed
[Validator] Completed inline documentation of the Node classes and the NodeTraverser
1 parent dbce5a2 commit 822fe47

File tree

10 files changed

+382
-130
lines changed

10 files changed

+382
-130
lines changed

‎src/Symfony/Component/Validator/Node/ClassNode.php‎

Lines changed: 22 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,13 @@
1818
/**
1919
* Represents an object and its class metadata in the validation graph.
2020
*
21+
* If the object is a collection which should be traversed, a new
22+
* {@link CollectionNode} instance will be created for that object:
23+
*
24+
* (TagList:ClassNode)
25+
* \
26+
* (TagList:CollectionNode)
27+
*
2128
* @since 2.5
2229
* @author Bernhard Schussek <[email protected]>
2330
*/
@@ -31,19 +38,22 @@ class ClassNode extends Node
3138
/**
3239
* Creates a new class node.
3340
*
34-
* @param object $object The validated object
35-
* @param ClassMetadataInterface $metadata The class metadata of that
36-
* object
37-
* @param string $propertyPath The property path leading
38-
* to this node
39-
* @param string[] $groups The groups in which this
40-
* node should be validated
41-
* @param string[]|null $cascadedGroups The groups in which
42-
* cascaded objects should be
43-
* validated
44-
* @param integer $traversalStrategy
41+
* @param object $object The validated object
42+
* @param ClassMetadataInterface $metadata The class metadata of
43+
* that object
44+
* @param string $propertyPath The property path leading
45+
* to this node
46+
* @param string[] $groups The groups in which this
47+
* node should be validated
48+
* @param string[]|null $cascadedGroups The groups in which
49+
* cascaded objects should
50+
* be validated
51+
* @param integer $traversalStrategy The strategy used for
52+
* traversing the object
53+
*
54+
* @throws UnexpectedTypeException If $object is not an object
4555
*
46-
* @throws \Symfony\Component\Validator\Exception\UnexpectedTypeException
56+
* @see \Symfony\Component\Validator\Mapping\TraversalStrategy
4757
*/
4858
public function __construct($object, ClassMetadataInterface $metadata, $propertyPath, array $groups, $cascadedGroups = null, $traversalStrategy = TraversalStrategy::IMPLICIT)
4959
{

‎src/Symfony/Component/Validator/Node/CollectionNode.php‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
use Symfony\Component\Validator\Mapping\TraversalStrategy;
1616

1717
/**
18-
* Represents an traversable collection in the validation graph.
18+
* Represents a traversable value in the validation graph.
1919
*
2020
* @since 2.5
2121
* @author Bernhard Schussek <[email protected]>
@@ -33,13 +33,19 @@ class CollectionNode extends Node
3333
* @param string[]|null $cascadedGroups The groups in which
3434
* cascaded objects should be
3535
* validated
36-
* @param integer $traversalStrategy The traversal strategy
36+
* @param integer $traversalStrategy The strategy used for
37+
* traversing the collection
3738
*
38-
* @throws \Symfony\Component\Validator\Exception\ConstraintDefinitionException
39+
* @throws ConstraintDefinitionException If $collection is not an array or a
40+
* \Traversable
41+
*
42+
* @see \Symfony\Component\Validator\Mapping\TraversalStrategy
3943
*/
4044
public function __construct($collection, $propertyPath, array $groups, $cascadedGroups = null, $traversalStrategy = TraversalStrategy::TRAVERSE)
4145
{
4246
if (!is_array($collection) && !$collection instanceof \Traversable) {
47+
// Must throw a ConstraintDefinitionException for backwards
48+
// compatibility reasons with Symfony < 2.5
4349
throw new ConstraintDefinitionException(sprintf(
4450
'Traversal was enabled for "%s", but this class '.
4551
'does not implement "\Traversable".',

‎src/Symfony/Component/Validator/Node/GenericNode.php‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,7 @@
1616
* attached to it.
1717
*
1818
* Together with {@link \Symfony\Component\Validator\Mapping\GenericMetadata},
19-
* this node type can be used to validate a value against some given
20-
* constraints.
19+
* this node type can be used to validate a value against some constraints.
2120
*
2221
* @since 2.5
2322
* @author Bernhard Schussek <[email protected]>

‎src/Symfony/Component/Validator/Node/Node.php‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
use Symfony\Component\Validator\Mapping\TraversalStrategy;
1717

1818
/**
19-
* A node in the validated graph.
19+
* A node in the validation graph.
2020
*
2121
* @since 2.5
2222
* @author Bernhard Schussek <[email protected]>
@@ -59,7 +59,11 @@ abstract class Node
5959
public $cascadedGroups;
6060

6161
/**
62+
* The strategy used for traversing the validated value.
63+
*
6264
* @var integer
65+
*
66+
* @see \Symfony\Component\Validator\Mapping\TraversalStrategy
6367
*/
6468
public $traversalStrategy;
6569

‎src/Symfony/Component/Validator/Node/PropertyNode.php‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,16 +19,23 @@
1919
* Represents the value of a property and its associated metadata.
2020
*
2121
* If the property contains an object and should be cascaded, a new
22-
* {@link ClassNode} instance will be created for that object.
23-
*
24-
* Example:
22+
* {@link ClassNode} instance will be created for that object:
2523
*
2624
* (Article:ClassNode)
2725
* \
28-
* (author:PropertyNode)
26+
* (->author:PropertyNode)
2927
* \
3028
* (Author:ClassNode)
3129
*
30+
* If the property contains a collection which should be traversed, a new
31+
* {@link CollectionNode} instance will be created for that collection:
32+
*
33+
* (Article:ClassNode)
34+
* \
35+
* (->tags:PropertyNode)
36+
* \
37+
* (array:CollectionNode)
38+
*
3239
* @since 2.5
3340
* @author Bernhard Schussek <[email protected]>
3441
*/
@@ -61,6 +68,8 @@ class PropertyNode extends Node
6168
* @param integer $traversalStrategy
6269
*
6370
* @throws UnexpectedTypeException If $object is not an object
71+
*
72+
* @see \Symfony\Component\Validator\Mapping\TraversalStrategy
6473
*/
6574
public function __construct($object, $value, PropertyMetadataInterface $metadata, $propertyPath, array $groups, $cascadedGroups = null, $traversalStrategy = TraversalStrategy::IMPLICIT)
6675
{

‎src/Symfony/Component/Validator/NodeTraverser/NodeTraverserInterface.php‎

Lines changed: 69 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,17 +12,85 @@
1212
namespace Symfony\Component\Validator\NodeTraverser;
1313

1414
use Symfony\Component\Validator\Context\ExecutionContextInterface;
15+
use Symfony\Component\Validator\Node\Node;
1516
use Symfony\Component\Validator\NodeVisitor\NodeVisitorInterface;
1617

1718
/**
18-
* @since %%NextVersion%%
19+
* Traverses the nodes of the validation graph.
20+
*
21+
* You can attach visitors to the traverser that are invoked during the
22+
* traversal. Before starting the traversal, the
23+
* {@link \Symfony\Component\Validator\NodeVisitor\NodeVisitorInterface::beforeTraversal()}
24+
* method of each visitor is called. For each node in the graph, the
25+
* {@link \Symfony\Component\Validator\NodeVisitor\NodeVisitorInterface::visit()}
26+
* of each visitor is called. At the end of the traversal, the traverser invokes
27+
* {@link \Symfony\Component\Validator\NodeVisitor\NodeVisitorInterface::afterTraversal()}
28+
* on each visitor.
29+
*
30+
* The visitors should be called in the same order in which they are added to
31+
* the traverser.
32+
*
33+
* The validation graph typically contains nodes of the following types:
34+
*
35+
* - {@link \Symfony\Component\Validator\Node\ClassNode}:
36+
* An object with associated class metadata
37+
* - {@link \Symfony\Component\Validator\Node\PropertyNode}:
38+
* A property value with associated property metadata
39+
* - {@link \Symfony\Component\Validator\Node\GenericNode}:
40+
* A generic value with associated constraints
41+
* - {@link \Symfony\Component\Validator\Node\CollectionNode}:
42+
* A traversable collection
43+
*
44+
* Generic nodes are mostly useful when you want to validate a value that has
45+
* neither associated class nor property metadata. Generic nodes usually come
46+
* with {@link \Symfony\Component\Validator\Mapping\GenericMetadata}, that
47+
* contains the constraints that the value should be validated against.
48+
*
49+
* Whenever a class, property or generic node is validated that contains a
50+
* traversable value which should be traversed (according to the
51+
* {@link \Symfony\Component\Validator\Mapping\TraversalStrategy} specified
52+
* in the node or its metadata), a new
53+
* {@link \Symfony\Component\Validator\Node\CollectionNode} will be attached
54+
* to the node graph.
55+
*
56+
* For example:
57+
*
58+
* (TagList:ClassNode)
59+
* \
60+
* (TagList:CollectionNode)
61+
*
62+
* When writing custom visitors, be aware that collection nodes usually contain
63+
* values that have already been passed to the visitor before through a class
64+
* node, a property node or a generic node.
65+
*
66+
* @since 2.5
1967
* @author Bernhard Schussek <[email protected]>
2068
*/
2169
interface NodeTraverserInterface
2270
{
71+
/**
72+
* Adds a new visitor to the traverser.
73+
*
74+
* Visitors that have already been added before are ignored.
75+
*
76+
* @param NodeVisitorInterface $visitor The visitor to add
77+
*/
2378
public function addVisitor(NodeVisitorInterface $visitor);
2479

80+
/**
81+
* Removes a visitor from the traverser.
82+
*
83+
* Non-existing visitors are ignored.
84+
*
85+
* @param NodeVisitorInterface $visitor The visitor to remove
86+
*/
2587
public function removeVisitor(NodeVisitorInterface $visitor);
2688

89+
/**
90+
* Traverses the given nodes in the given context.
91+
*
92+
* @param Node[] $nodes The nodes to traverse
93+
* @param ExecutionContextInterface $context The validation context
94+
*/
2795
public function traverse(array $nodes, ExecutionContextInterface $context);
2896
}

0 commit comments

Comments
 (0)