4 * This file is part of the Symfony package.
6 * (c) Fabien Potencier <fabien@symfony.com>
8 * For the full copyright and license information, please view the LICENSE
9 * file that was distributed with this source code.
12 namespace Symfony\Component\Validator;
15 * Stores the validator's state during validation.
17 * For example, let's validate the following object graph:
20 * (Person)---($firstName: string)
22 * ($address: Address)---($street: string)
25 * We validate the <tt>Person</tt> instance, which becomes the "root" of the
26 * validation run (see {@link getRoot}). The state of the context after the
27 * first step will be like this:
30 * (Person)---($firstName: string)
32 * ($address: Address)---($street: string)
35 * The validator is stopped at the <tt>Person</tt> node, both the root and the
36 * value (see {@link getValue}) of the context point to the <tt>Person</tt>
37 * instance. The property path is empty at this point (see {@link getPropertyPath}).
38 * The metadata of the context is the metadata of the <tt>Person</tt> node
39 * (see {@link getMetadata}).
41 * After advancing to the property <tt>$firstName</tt> of the <tt>Person</tt>
42 * instance, the state of the context looks like this:
45 * (Person)---($firstName: string)
47 * ($address: Address)---($street: string)
50 * The validator is stopped at the property <tt>$firstName</tt>. The root still
51 * points to the <tt>Person</tt> instance, because this is where the validation
52 * started. The property path is now "firstName" and the current value is the
53 * value of that property.
55 * After advancing to the <tt>$address</tt> property and then to the
56 * <tt>$street</tt> property of the <tt>Address</tt> instance, the context state
60 * (Person)---($firstName: string)
62 * ($address: Address)---($street: string)
66 * The validator is stopped at the property <tt>$street</tt>. The root still
67 * points to the <tt>Person</tt> instance, but the property path is now
68 * "address.street" and the validated value is the value of that property.
70 * Apart from the root, the property path and the currently validated value,
71 * the execution context also knows the metadata of the current node (see
72 * {@link getMetadata}) which for example returns a {@link Mapping\PropertyMetadata}
73 * or a {@link Mapping\ClassMetadata} object. he context also contains the
74 * validation group that is currently being validated (see {@link getGroup}) and
75 * the violations that happened up until now (see {@link getViolations}).
77 * Apart from reading the execution context, you can also use
78 * {@link addViolation} or {@link addViolationAt} to add new violations and
79 * {@link validate} or {@link validateValue} to validate values that the
80 * validator otherwise would not reach.
82 * @author Bernhard Schussek <bschussek@gmail.com>
84 * @deprecated since version 2.5, to be removed in 3.0.
85 * Use {@link Context\ExecutionContextInterface} instead.
87 interface ExecutionContextInterface
90 * Adds a violation at the current node of the validation graph.
92 * Note: the parameters $invalidValue, $plural and $code are deprecated since version 2.5 and will be removed in 3.0.
94 * @param string $message The error message
95 * @param array $params The parameters substituted in the error message
96 * @param mixed $invalidValue The invalid, validated value
97 * @param int|null $plural The number to use to pluralize of the message
98 * @param int|null $code The violation code
100 public function addViolation($message, array $params = array(), $invalidValue = null, $plural = null, $code = null);
103 * Adds a violation at the validation graph node with the given property
104 * path relative to the current property path.
106 * @param string $subPath The relative property path for the violation
107 * @param string $message The error message
108 * @param array $parameters The parameters substituted in the error message
109 * @param mixed $invalidValue The invalid, validated value
110 * @param int|null $plural The number to use to pluralize of the message
111 * @param int|null $code The violation code
113 * @deprecated since version 2.5, to be removed in 3.0.
114 * Use {@link Context\ExecutionContextInterface::buildViolation()}
117 public function addViolationAt($subPath, $message, array $parameters = array(), $invalidValue = null, $plural = null, $code = null);
120 * Validates the given value within the scope of the current validation.
122 * The value may be any value recognized by the used metadata factory
123 * (see {@link MetadataFactoryInterface::getMetadata}), or an array or a
124 * traversable object of such values.
126 * Usually you validate a value that is not the current node of the
127 * execution context. For this case, you can pass the {@link $subPath}
128 * argument which is appended to the current property path when a violation
129 * is created. For example, take the following object graph:
132 * (Person)---($address: Address)---($phoneNumber: PhoneNumber)
136 * When the execution context stops at the <tt>Person</tt> instance, the
137 * property path is "address". When you validate the <tt>PhoneNumber</tt>
138 * instance now, pass "phoneNumber" as sub path to correct the property path
139 * to "address.phoneNumber":
142 * $context->validate($address->phoneNumber, 'phoneNumber');
145 * Any violations generated during the validation will be added to the
146 * violation list that you can access with {@link getViolations}.
148 * @param mixed $value The value to validate
149 * @param string $subPath The path to append to the context's property path
150 * @param null|string|string[] $groups The groups to validate in. If you don't pass any
151 * groups here, the current group of the context
153 * @param bool $traverse Whether to traverse the value if it is an array
154 * or an instance of <tt>\Traversable</tt>.
155 * @param bool $deep Whether to traverse the value recursively if
156 * it is a collection of collections.
158 * @deprecated since version 2.5, to be removed in 3.0.
159 * Use {@link Context\ExecutionContextInterface::getValidator()}
162 public function validate($value, $subPath = '', $groups = null, $traverse = false, $deep = false);
165 * Validates a value against a constraint.
167 * Use the parameter <tt>$subPath</tt> to adapt the property path for the
168 * validated value. For example, take the following object graph:
171 * (Person)---($address: Address)---($street: string)
175 * When the validator validates the <tt>Address</tt> instance, the
176 * property path stored in the execution context is "address". When you
177 * manually validate the property <tt>$street</tt> now, pass the sub path
178 * "street" to adapt the full property path to "address.street":
181 * $context->validate($address->street, new NotNull(), 'street');
184 * @param mixed $value The value to validate
185 * @param Constraint|Constraint[] $constraints The constraint(s) to validate against
186 * @param string $subPath The path to append to the context's property path
187 * @param null|string|string[] $groups The groups to validate in. If you don't pass any
188 * groups here, the current group of the context
191 * @deprecated since version 2.5, to be removed in 3.0.
192 * Use {@link Context\ExecutionContextInterface::getValidator()}
195 public function validateValue($value, $constraints, $subPath = '', $groups = null);
198 * Returns the violations generated by the validator so far.
200 * @return ConstraintViolationListInterface The constraint violation list
202 public function getViolations();
205 * Returns the value at which validation was started in the object graph.
207 * The validator, when given an object, traverses the properties and
208 * related objects and their properties. The root of the validation is the
209 * object from which the traversal started.
211 * The current value is returned by {@link getValue}.
213 * @return mixed The root value of the validation
215 public function getRoot();
218 * Returns the value that the validator is currently validating.
220 * If you want to retrieve the object that was originally passed to the
221 * validator, use {@link getRoot}.
223 * @return mixed The currently validated value
225 public function getValue();
228 * Returns the metadata for the currently validated value.
230 * With the core implementation, this method returns a
231 * {@link Mapping\ClassMetadata} instance if the current value is an object,
232 * a {@link Mapping\PropertyMetadata} instance if the current value is
233 * the value of a property and a {@link Mapping\GetterMetadata} instance if
234 * the validated value is the result of a getter method.
236 * If the validated value is neither of these, for example if the validator
237 * has been called with a plain value and constraint, this method returns
240 * @return MetadataInterface|null The metadata of the currently validated
243 public function getMetadata();
246 * Returns the used metadata factory.
248 * @return MetadataFactoryInterface The metadata factory
250 * @deprecated since version 2.5, to be removed in 3.0.
251 * Use {@link Context\ExecutionContextInterface::getValidator()}
253 * {@link Validator\ValidatorInterface::getMetadataFor()} or
254 * {@link Validator\ValidatorInterface::hasMetadataFor()} there.
256 public function getMetadataFactory();
259 * Returns the validation group that is currently being validated.
261 * @return string The current validation group
263 public function getGroup();
266 * Returns the class name of the current node.
268 * If the metadata of the current node does not implement
269 * {@link ClassBasedInterface} or if no metadata is available for the
270 * current node, this method returns null.
272 * @return string|null The class name or null, if no class name could be found
274 public function getClassName();
277 * Returns the property name of the current node.
279 * If the metadata of the current node does not implement
280 * {@link PropertyMetadataInterface} or if no metadata is available for the
281 * current node, this method returns null.
283 * @return string|null The property name or null, if no property name could be found
285 public function getPropertyName();
288 * Returns the property path to the value that the validator is currently
291 * For example, take the following object graph:
294 * (Person)---($address: Address)---($street: string)
297 * When the <tt>Person</tt> instance is passed to the validator, the
298 * property path is initially empty. When the <tt>$address</tt> property
299 * of that person is validated, the property path is "address". When
300 * the <tt>$street</tt> property of the related <tt>Address</tt> instance
301 * is validated, the property path is "address.street".
303 * Properties of objects are prefixed with a dot in the property path.
304 * Indices of arrays or objects implementing the {@link \ArrayAccess}
305 * interface are enclosed in brackets. For example, if the property in
306 * the previous example is <tt>$addresses</tt> and contains an array
307 * of <tt>Address</tt> instance, the property path generated for the
308 * <tt>$street</tt> property of one of these addresses is for example
309 * "addresses[0].street".
311 * @param string $subPath Optional. The suffix appended to the current
314 * @return string The current property path. The result may be an empty
315 * string if the validator is currently validating the
316 * root value of the validation graph.
318 public function getPropertyPath($subPath = '');