Skip to content

Commit 524a953

Browse files
webmozartwebmozart
committed
[Validator] Improved inline documentation of the validators
1 parent 9986f03 commit 524a953

File tree

5 files changed

+164
-61
lines changed

5 files changed

+164
-61
lines changed

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

+41-8
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,9 @@
2424
use Symfony\Component\Validator\Util\PropertyPath;
2525

2626
/**
27-
* @since %%NextVersion%%
27+
* Default implementation of {@link ContextualValidatorInterface}.
28+
*
29+
* @since 2.5
2830
* @author Bernhard Schussek <bschussek@gmail.com>
2931
*/
3032
class ContextualValidator implements ContextualValidatorInterface
@@ -44,6 +46,15 @@ class ContextualValidator implements ContextualValidatorInterface
4446
*/
4547
private $metadataFactory;
4648

49+
/**
50+
* Creates a validator for the given context.
51+
*
52+
* @param ExecutionContextInterface $context The execution context
53+
* @param NodeTraverserInterface $nodeTraverser The node traverser
54+
* @param MetadataFactoryInterface $metadataFactory The factory for fetching
55+
* the metadata of validated
56+
* objects
57+
*/
4758
public function __construct(ExecutionContextInterface $context, NodeTraverserInterface $nodeTraverser, MetadataFactoryInterface $metadataFactory)
4859
{
4960
$this->context = $context;
@@ -53,13 +64,19 @@ public function __construct(ExecutionContextInterface $context, NodeTraverserInt
5364
$this->metadataFactory = $metadataFactory;
5465
}
5566

56-
public function atPath($subPath)
67+
/**
68+
* {@inheritdoc}
69+
*/
70+
public function atPath($path)
5771
{
58-
$this->defaultPropertyPath = $this->context->getPropertyPath($subPath);
72+
$this->defaultPropertyPath = $this->context->getPropertyPath($path);
5973

6074
return $this;
6175
}
6276

77+
/**
78+
* {@inheritdoc}
79+
*/
6380
public function validate($value, $constraints = null, $groups = null)
6481
{
6582
if (null === $constraints) {
@@ -84,6 +101,9 @@ public function validate($value, $constraints = null, $groups = null)
84101
return $this;
85102
}
86103

104+
/**
105+
* {@inheritdoc}
106+
*/
87107
public function validateProperty($object, $propertyName, $groups = null)
88108
{
89109
$classMetadata = $this->metadataFactory->getMetadataFor($object);
@@ -118,6 +138,9 @@ public function validateProperty($object, $propertyName, $groups = null)
118138
return $this;
119139
}
120140

141+
/**
142+
* {@inheritdoc}
143+
*/
121144
public function validatePropertyValue($object, $propertyName, $value, $groups = null)
122145
{
123146
$classMetadata = $this->metadataFactory->getMetadataFor($object);
@@ -151,6 +174,21 @@ public function validatePropertyValue($object, $propertyName, $value, $groups =
151174
return $this;
152175
}
153176

177+
/**
178+
* {@inheritdoc}
179+
*/
180+
public function getViolations()
181+
{
182+
return $this->context->getViolations();
183+
}
184+
185+
/**
186+
* Normalizes the given group or list of groups to an array.
187+
*
188+
* @param mixed $groups The groups to normalize
189+
*
190+
* @return array A group array
191+
*/
154192
protected function normalizeGroups($groups)
155193
{
156194
if (is_array($groups)) {
@@ -159,9 +197,4 @@ protected function normalizeGroups($groups)
159197

160198
return array($groups);
161199
}
162-
163-
public function getViolations()
164-
{
165-
return $this->context->getViolations();
166-
}
167200
}

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

+34-23
Original file line numberDiff line numberDiff line change
@@ -15,64 +15,75 @@
1515
use Symfony\Component\Validator\ConstraintViolationListInterface;
1616

1717
/**
18-
* @since %%NextVersion%%
18+
* A validator in a specific execution context.
19+
*
20+
* @since 2.5
1921
* @author Bernhard Schussek <bschussek@gmail.com>
2022
*/
2123
interface ContextualValidatorInterface
2224
{
2325
/**
24-
* @param string $subPath
26+
* Appends the given path to the property path of the context.
27+
*
28+
* If called multiple times, the path will always be reset to the context's
29+
* original path with the given path appended to it.
30+
*
31+
* @param string $path The path to append
2532
*
2633
* @return ContextualValidatorInterface This validator
2734
*/
28-
public function atPath($subPath);
35+
public function atPath($path);
2936

3037
/**
3138
* Validates a value against a constraint or a list of constraints.
3239
*
3340
* If no constraint is passed, the constraint
3441
* {@link \Symfony\Component\Validator\Constraints\Valid} is assumed.
3542
*
36-
* @param mixed $value The value to validate.
37-
* @param Constraint|Constraint[] $constraints The constraint(s) to validate against.
38-
* @param array|null $groups The validation groups to validate.
43+
* @param mixed $value The value to validate
44+
* @param Constraint|Constraint[] $constraints The constraint(s) to validate
45+
* against
46+
* @param array|null $groups The validation groups to
47+
* validate. If none is given,
48+
* "Default" is assumed
3949
*
4050
* @return ContextualValidatorInterface This validator
4151
*/
4252
public function validate($value, $constraints = null, $groups = null);
4353

4454
/**
45-
* Validates a property of a value against its current value.
55+
* Validates a property of an object against the constraints specified
56+
* for this property.
4657
*
47-
* The accepted values depend on the {@link MetadataFactoryInterface}
48-
* implementation.
49-
*
50-
* @param mixed $object The value containing the property.
51-
* @param string $propertyName The name of the property to validate.
52-
* @param array|null $groups The validation groups to validate.
58+
* @param object $object The object
59+
* @param string $propertyName The name of the validated property
60+
* @param array|null $groups The validation groups to validate. If
61+
* none is given, "Default" is assumed
5362
*
5463
* @return ContextualValidatorInterface This validator
5564
*/
5665
public function validateProperty($object, $propertyName, $groups = null);
5766

5867
/**
59-
* Validate a property of a value against a potential value.
60-
*
61-
* The accepted values depend on the {@link MetadataFactoryInterface}
62-
* implementation.
68+
* Validates a value against the constraints specified for an object's
69+
* property.
6370
*
64-
* @param string $object The value containing the property.
65-
* @param string $propertyName The name of the property to validate
66-
* @param string $value The value to validate against the
67-
* constraints of the property.
68-
* @param array|null $groups The validation groups to validate.
71+
* @param object $object The object
72+
* @param string $propertyName The name of the property
73+
* @param mixed $value The value to validate against the
74+
* property's constraints
75+
* @param array|null $groups The validation groups to validate. If
76+
* none is given, "Default" is assumed
6977
*
7078
* @return ContextualValidatorInterface This validator
7179
*/
7280
public function validatePropertyValue($object, $propertyName, $value, $groups = null);
7381

7482
/**
75-
* @return ConstraintViolationListInterface
83+
* Returns the violations that have been generated so far in the context
84+
* of the validator.
85+
*
86+
* @return ConstraintViolationListInterface The constraint violations
7687
*/
7788
public function getViolations();
7889
}

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

+5
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,14 @@
1717
use Symfony\Component\Validator\ValidatorInterface as LegacyValidatorInterface;
1818

1919
/**
20+
* A validator that supports both the API of Symfony < 2.5 and Symfony 2.5+.
21+
*
2022
* @since 2.5
2123
* @author Bernhard Schussek <bschussek@gmail.com>
2224
*
25+
* @see \Symfony\Component\Validator\ValidatorInterface
26+
* @see \Symfony\Component\Validator\Validator\ValidatorInterface
27+
*
2328
* @deprecated Implemented for backwards compatibility with Symfony < 2.5.
2429
* To be removed in Symfony 3.0.
2530
*/

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

+22-1
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,9 @@
1717
use Symfony\Component\Validator\MetadataFactoryInterface;
1818

1919
/**
20-
* @since %%NextVersion%%
20+
* Default implementation of {@link ValidatorInterface}.
21+
*
22+
* @since 2.5
2123
* @author Bernhard Schussek <bschussek@gmail.com>
2224
*/
2325
class Validator implements ValidatorInterface
@@ -37,6 +39,16 @@ class Validator implements ValidatorInterface
3739
*/
3840
protected $metadataFactory;
3941

42+
/**
43+
* Creates a new validator.
44+
*
45+
* @param ExecutionContextFactoryInterface $contextFactory The factory for
46+
* creating new contexts
47+
* @param NodeTraverserInterface $nodeTraverser The node traverser
48+
* @param MetadataFactoryInterface $metadataFactory The factory for
49+
* fetching the metadata
50+
* of validated objects
51+
*/
4052
public function __construct(ExecutionContextFactoryInterface $contextFactory, NodeTraverserInterface $nodeTraverser, MetadataFactoryInterface $metadataFactory)
4153
{
4254
$this->contextFactory = $contextFactory;
@@ -84,20 +96,29 @@ public function hasMetadataFor($object)
8496
return $this->metadataFactory->hasMetadataFor($object);
8597
}
8698

99+
/**
100+
* {@inheritdoc}
101+
*/
87102
public function validate($value, $constraints = null, $groups = null)
88103
{
89104
return $this->startContext($value)
90105
->validate($value, $constraints, $groups)
91106
->getViolations();
92107
}
93108

109+
/**
110+
* {@inheritdoc}
111+
*/
94112
public function validateProperty($object, $propertyName, $groups = null)
95113
{
96114
return $this->startContext($object)
97115
->validateProperty($object, $propertyName, $groups)
98116
->getViolations();
99117
}
100118

119+
/**
120+
* {@inheritdoc}
121+
*/
101122
public function validatePropertyValue($object, $propertyName, $value, $groups = null)
102123
{
103124
return $this->startContext($object)

0 commit comments

Comments
 (0)