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\Context;
14 use Symfony\Component\Validator\Constraint;
15 use Symfony\Component\Validator\ConstraintViolationListInterface;
16 use Symfony\Component\Validator\Mapping;
17 use Symfony\Component\Validator\Mapping\MetadataInterface;
18 use Symfony\Component\Validator\Validator\ValidatorInterface;
19 use Symfony\Component\Validator\Violation\ConstraintViolationBuilderInterface;
22 * The context of a validation run.
24 * The context collects all violations generated during the validation. By
25 * default, validators execute all validations in a new context:
27 * $violations = $validator->validate($object);
29 * When you make another call to the validator, while the validation is in
30 * progress, the violations will be isolated from each other:
32 * public function validate($value, Constraint $constraint)
34 * $validator = $this->context->getValidator();
36 * // The violations are not added to $this->context
37 * $violations = $validator->validate($value);
40 * However, if you want to add the violations to the current context, use the
41 * {@link ValidatorInterface::inContext()} method:
43 * public function validate($value, Constraint $constraint)
45 * $validator = $this->context->getValidator();
47 * // The violations are added to $this->context
49 * ->inContext($this->context)
54 * Additionally, the context provides information about the current state of
55 * the validator, such as the currently validated class, the name of the
56 * currently validated property and more. These values change over time, so you
57 * cannot store a context and expect that the methods still return the same
60 * @author Bernhard Schussek <bschussek@gmail.com>
62 interface ExecutionContextInterface
65 * Adds a violation at the current node of the validation graph.
67 * @param string $message The error message
68 * @param array $params The parameters substituted in the error message
70 public function addViolation($message, array $params = array());
73 * Returns a builder for adding a violation with extended information.
75 * Call {@link ConstraintViolationBuilderInterface::addViolation()} to
76 * add the violation when you're done with the configuration:
78 * $context->buildViolation('Please enter a number between %min% and %max%.')
79 * ->setParameter('%min%', 3)
80 * ->setParameter('%max%', 10)
81 * ->setTranslationDomain('number_validation')
84 * @param string $message The error message
85 * @param array $parameters The parameters substituted in the error message
87 * @return ConstraintViolationBuilderInterface The violation builder
89 public function buildViolation($message, array $parameters = array());
92 * Returns the validator.
94 * Useful if you want to validate additional constraints:
96 * public function validate($value, Constraint $constraint)
98 * $validator = $this->context->getValidator();
100 * $violations = $validator->validate($value, new Length(array('min' => 3)));
102 * if (count($violations) > 0) {
107 * @return ValidatorInterface
109 public function getValidator();
112 * Returns the currently validated object.
114 * If the validator is currently validating a class constraint, the
115 * object of that class is returned. If it is a validating a property or
116 * getter constraint, the object that the property/getter belongs to is
119 * In other cases, null is returned.
121 * @return object|null The currently validated object or null
123 public function getObject();
126 * Sets the currently validated value.
128 * @param mixed $value The validated value
129 * @param object|null $object The currently validated object
130 * @param MetadataInterface|null $metadata The validation metadata
131 * @param string $propertyPath The property path to the current value
133 * @internal Used by the validator engine. Should not be called by user
136 public function setNode($value, $object, MetadataInterface $metadata = null, $propertyPath);
139 * Sets the currently validated group.
141 * @param string|null $group The validated group
143 * @internal Used by the validator engine. Should not be called by user
146 public function setGroup($group);
149 * Sets the currently validated constraint.
151 * @param Constraint $constraint The validated constraint
153 * @internal Used by the validator engine. Should not be called by user
156 public function setConstraint(Constraint $constraint);
159 * Marks an object as validated in a specific validation group.
161 * @param string $cacheKey The hash of the object
162 * @param string $groupHash The group's name or hash, if it is group
165 * @internal Used by the validator engine. Should not be called by user
168 public function markGroupAsValidated($cacheKey, $groupHash);
171 * Returns whether an object was validated in a specific validation group.
173 * @param string $cacheKey The hash of the object
174 * @param string $groupHash The group's name or hash, if it is group
177 * @return bool Whether the object was already validated for that
180 * @internal Used by the validator engine. Should not be called by user
183 public function isGroupValidated($cacheKey, $groupHash);
186 * Marks a constraint as validated for an object.
188 * @param string $cacheKey The hash of the object
189 * @param string $constraintHash The hash of the constraint
191 * @internal Used by the validator engine. Should not be called by user
194 public function markConstraintAsValidated($cacheKey, $constraintHash);
197 * Returns whether a constraint was validated for an object.
199 * @param string $cacheKey The hash of the object
200 * @param string $constraintHash The hash of the constraint
202 * @return bool Whether the constraint was already validated
204 * @internal Used by the validator engine. Should not be called by user
207 public function isConstraintValidated($cacheKey, $constraintHash);
210 * Marks that an object was initialized.
212 * @param string $cacheKey The hash of the object
214 * @internal Used by the validator engine. Should not be called by user
217 * @see ObjectInitializerInterface
219 public function markObjectAsInitialized($cacheKey);
222 * Returns whether an object was initialized.
224 * @param string $cacheKey The hash of the object
226 * @return bool Whether the object was already initialized
228 * @internal Used by the validator engine. Should not be called by user
231 * @see ObjectInitializerInterface
233 public function isObjectInitialized($cacheKey);
236 * Returns the violations generated by the validator so far.
238 * @return ConstraintViolationListInterface The constraint violation list
240 public function getViolations();
243 * Returns the value at which validation was started in the object graph.
245 * The validator, when given an object, traverses the properties and
246 * related objects and their properties. The root of the validation is the
247 * object from which the traversal started.
249 * The current value is returned by {@link getValue}.
251 * @return mixed The root value of the validation
253 public function getRoot();
256 * Returns the value that the validator is currently validating.
258 * If you want to retrieve the object that was originally passed to the
259 * validator, use {@link getRoot}.
261 * @return mixed The currently validated value
263 public function getValue();
266 * Returns the metadata for the currently validated value.
268 * With the core implementation, this method returns a
269 * {@link Mapping\ClassMetadataInterface} instance if the current value is an object,
270 * a {@link Mapping\PropertyMetadata} instance if the current value is
271 * the value of a property and a {@link Mapping\GetterMetadata} instance if
272 * the validated value is the result of a getter method.
274 * If the validated value is neither of these, for example if the validator
275 * has been called with a plain value and constraint, this method returns
278 * @return MetadataInterface|null the metadata of the currently validated
281 public function getMetadata();
284 * Returns the validation group that is currently being validated.
286 * @return string The current validation group
288 public function getGroup();
291 * Returns the class name of the current node.
293 * If the metadata of the current node does not implement
294 * {@link Mapping\ClassMetadataInterface} or if no metadata is available for the
295 * current node, this method returns null.
297 * @return string|null The class name or null, if no class name could be found
299 public function getClassName();
302 * Returns the property name of the current node.
304 * If the metadata of the current node does not implement
305 * {@link PropertyMetadataInterface} or if no metadata is available for the
306 * current node, this method returns null.
308 * @return string|null The property name or null, if no property name could be found
310 public function getPropertyName();
313 * Returns the property path to the value that the validator is currently
316 * For example, take the following object graph:
319 * (Person)---($address: Address)---($street: string)
322 * When the <tt>Person</tt> instance is passed to the validator, the
323 * property path is initially empty. When the <tt>$address</tt> property
324 * of that person is validated, the property path is "address". When
325 * the <tt>$street</tt> property of the related <tt>Address</tt> instance
326 * is validated, the property path is "address.street".
328 * Properties of objects are prefixed with a dot in the property path.
329 * Indices of arrays or objects implementing the {@link \ArrayAccess}
330 * interface are enclosed in brackets. For example, if the property in
331 * the previous example is <tt>$addresses</tt> and contains an array
332 * of <tt>Address</tt> instance, the property path generated for the
333 * <tt>$street</tt> property of one of these addresses is for example
334 * "addresses[0].street".
336 * @param string $subPath Optional. The suffix appended to the current
339 * @return string The current property path. The result may be an empty
340 * string if the validator is currently validating the
341 * root value of the validation graph.
343 public function getPropertyPath($subPath = '');