Chris@0: <?php
Chris@0: 
Chris@0: /*
Chris@0:  * This file is part of the Symfony package.
Chris@0:  *
Chris@0:  * (c) Fabien Potencier <fabien@symfony.com>
Chris@0:  *
Chris@0:  * For the full copyright and license information, please view the LICENSE
Chris@0:  * file that was distributed with this source code.
Chris@0:  */
Chris@0: 
Chris@0: namespace Symfony\Component\Validator\Context;
Chris@0: 
Chris@0: use Symfony\Component\Validator\Constraint;
Chris@17: use Symfony\Component\Validator\ConstraintViolationListInterface;
Chris@0: use Symfony\Component\Validator\Mapping;
Chris@0: use Symfony\Component\Validator\Mapping\MetadataInterface;
Chris@0: use Symfony\Component\Validator\Validator\ValidatorInterface;
Chris@0: use Symfony\Component\Validator\Violation\ConstraintViolationBuilderInterface;
Chris@0: 
Chris@0: /**
Chris@0:  * The context of a validation run.
Chris@0:  *
Chris@0:  * The context collects all violations generated during the validation. By
Chris@0:  * default, validators execute all validations in a new context:
Chris@0:  *
Chris@0:  *     $violations = $validator->validate($object);
Chris@0:  *
Chris@0:  * When you make another call to the validator, while the validation is in
Chris@0:  * progress, the violations will be isolated from each other:
Chris@0:  *
Chris@0:  *     public function validate($value, Constraint $constraint)
Chris@0:  *     {
Chris@0:  *         $validator = $this->context->getValidator();
Chris@0:  *
Chris@0:  *         // The violations are not added to $this->context
Chris@0:  *         $violations = $validator->validate($value);
Chris@0:  *     }
Chris@0:  *
Chris@0:  * However, if you want to add the violations to the current context, use the
Chris@0:  * {@link ValidatorInterface::inContext()} method:
Chris@0:  *
Chris@0:  *     public function validate($value, Constraint $constraint)
Chris@0:  *     {
Chris@0:  *         $validator = $this->context->getValidator();
Chris@0:  *
Chris@0:  *         // The violations are added to $this->context
Chris@0:  *         $validator
Chris@0:  *             ->inContext($this->context)
Chris@0:  *             ->validate($value)
Chris@0:  *         ;
Chris@0:  *     }
Chris@0:  *
Chris@0:  * Additionally, the context provides information about the current state of
Chris@0:  * the validator, such as the currently validated class, the name of the
Chris@0:  * currently validated property and more. These values change over time, so you
Chris@0:  * cannot store a context and expect that the methods still return the same
Chris@0:  * results later on.
Chris@0:  *
Chris@0:  * @author Bernhard Schussek <bschussek@gmail.com>
Chris@0:  */
Chris@0: interface ExecutionContextInterface
Chris@0: {
Chris@0:     /**
Chris@0:      * Adds a violation at the current node of the validation graph.
Chris@0:      *
Chris@0:      * @param string $message The error message
Chris@0:      * @param array  $params  The parameters substituted in the error message
Chris@0:      */
Chris@17:     public function addViolation($message, array $params = []);
Chris@0: 
Chris@0:     /**
Chris@0:      * Returns a builder for adding a violation with extended information.
Chris@0:      *
Chris@0:      * Call {@link ConstraintViolationBuilderInterface::addViolation()} to
Chris@0:      * add the violation when you're done with the configuration:
Chris@0:      *
Chris@0:      *     $context->buildViolation('Please enter a number between %min% and %max%.')
Chris@0:      *         ->setParameter('%min%', 3)
Chris@0:      *         ->setParameter('%max%', 10)
Chris@0:      *         ->setTranslationDomain('number_validation')
Chris@0:      *         ->addViolation();
Chris@0:      *
Chris@0:      * @param string $message    The error message
Chris@0:      * @param array  $parameters The parameters substituted in the error message
Chris@0:      *
Chris@0:      * @return ConstraintViolationBuilderInterface The violation builder
Chris@0:      */
Chris@17:     public function buildViolation($message, array $parameters = []);
Chris@0: 
Chris@0:     /**
Chris@0:      * Returns the validator.
Chris@0:      *
Chris@0:      * Useful if you want to validate additional constraints:
Chris@0:      *
Chris@0:      *     public function validate($value, Constraint $constraint)
Chris@0:      *     {
Chris@0:      *         $validator = $this->context->getValidator();
Chris@0:      *
Chris@17:      *         $violations = $validator->validate($value, new Length(['min' => 3]));
Chris@0:      *
Chris@0:      *         if (count($violations) > 0) {
Chris@0:      *             // ...
Chris@0:      *         }
Chris@0:      *     }
Chris@0:      *
Chris@0:      * @return ValidatorInterface
Chris@0:      */
Chris@0:     public function getValidator();
Chris@0: 
Chris@0:     /**
Chris@0:      * Returns the currently validated object.
Chris@0:      *
Chris@0:      * If the validator is currently validating a class constraint, the
Chris@17:      * object of that class is returned. If it is validating a property or
Chris@0:      * getter constraint, the object that the property/getter belongs to is
Chris@0:      * returned.
Chris@0:      *
Chris@0:      * In other cases, null is returned.
Chris@0:      *
Chris@0:      * @return object|null The currently validated object or null
Chris@0:      */
Chris@0:     public function getObject();
Chris@0: 
Chris@0:     /**
Chris@0:      * Sets the currently validated value.
Chris@0:      *
Chris@0:      * @param mixed                  $value        The validated value
Chris@0:      * @param object|null            $object       The currently validated object
Chris@0:      * @param MetadataInterface|null $metadata     The validation metadata
Chris@0:      * @param string                 $propertyPath The property path to the current value
Chris@0:      *
Chris@0:      * @internal Used by the validator engine. Should not be called by user
Chris@0:      *           code.
Chris@0:      */
Chris@0:     public function setNode($value, $object, MetadataInterface $metadata = null, $propertyPath);
Chris@0: 
Chris@0:     /**
Chris@0:      * Sets the currently validated group.
Chris@0:      *
Chris@0:      * @param string|null $group The validated group
Chris@0:      *
Chris@0:      * @internal Used by the validator engine. Should not be called by user
Chris@0:      *           code.
Chris@0:      */
Chris@0:     public function setGroup($group);
Chris@0: 
Chris@0:     /**
Chris@0:      * Sets the currently validated constraint.
Chris@0:      *
Chris@0:      * @param Constraint $constraint The validated constraint
Chris@0:      *
Chris@0:      * @internal Used by the validator engine. Should not be called by user
Chris@0:      *           code.
Chris@0:      */
Chris@0:     public function setConstraint(Constraint $constraint);
Chris@0: 
Chris@0:     /**
Chris@0:      * Marks an object as validated in a specific validation group.
Chris@0:      *
Chris@0:      * @param string $cacheKey  The hash of the object
Chris@0:      * @param string $groupHash The group's name or hash, if it is group
Chris@0:      *                          sequence
Chris@0:      *
Chris@0:      * @internal Used by the validator engine. Should not be called by user
Chris@0:      *           code.
Chris@0:      */
Chris@0:     public function markGroupAsValidated($cacheKey, $groupHash);
Chris@0: 
Chris@0:     /**
Chris@0:      * Returns whether an object was validated in a specific validation group.
Chris@0:      *
Chris@0:      * @param string $cacheKey  The hash of the object
Chris@0:      * @param string $groupHash The group's name or hash, if it is group
Chris@0:      *                          sequence
Chris@0:      *
Chris@0:      * @return bool Whether the object was already validated for that
Chris@0:      *              group
Chris@0:      *
Chris@0:      * @internal Used by the validator engine. Should not be called by user
Chris@0:      *           code.
Chris@0:      */
Chris@0:     public function isGroupValidated($cacheKey, $groupHash);
Chris@0: 
Chris@0:     /**
Chris@0:      * Marks a constraint as validated for an object.
Chris@0:      *
Chris@0:      * @param string $cacheKey       The hash of the object
Chris@0:      * @param string $constraintHash The hash of the constraint
Chris@0:      *
Chris@0:      * @internal Used by the validator engine. Should not be called by user
Chris@0:      *           code.
Chris@0:      */
Chris@0:     public function markConstraintAsValidated($cacheKey, $constraintHash);
Chris@0: 
Chris@0:     /**
Chris@0:      * Returns whether a constraint was validated for an object.
Chris@0:      *
Chris@0:      * @param string $cacheKey       The hash of the object
Chris@0:      * @param string $constraintHash The hash of the constraint
Chris@0:      *
Chris@0:      * @return bool Whether the constraint was already validated
Chris@0:      *
Chris@0:      * @internal Used by the validator engine. Should not be called by user
Chris@0:      *           code.
Chris@0:      */
Chris@0:     public function isConstraintValidated($cacheKey, $constraintHash);
Chris@0: 
Chris@0:     /**
Chris@0:      * Marks that an object was initialized.
Chris@0:      *
Chris@0:      * @param string $cacheKey The hash of the object
Chris@0:      *
Chris@0:      * @internal Used by the validator engine. Should not be called by user
Chris@0:      *           code.
Chris@0:      *
Chris@0:      * @see ObjectInitializerInterface
Chris@0:      */
Chris@0:     public function markObjectAsInitialized($cacheKey);
Chris@0: 
Chris@0:     /**
Chris@0:      * Returns whether an object was initialized.
Chris@0:      *
Chris@0:      * @param string $cacheKey The hash of the object
Chris@0:      *
Chris@0:      * @return bool Whether the object was already initialized
Chris@0:      *
Chris@0:      * @internal Used by the validator engine. Should not be called by user
Chris@0:      *           code.
Chris@0:      *
Chris@0:      * @see ObjectInitializerInterface
Chris@0:      */
Chris@0:     public function isObjectInitialized($cacheKey);
Chris@0: 
Chris@0:     /**
Chris@0:      * Returns the violations generated by the validator so far.
Chris@0:      *
Chris@0:      * @return ConstraintViolationListInterface The constraint violation list
Chris@0:      */
Chris@0:     public function getViolations();
Chris@0: 
Chris@0:     /**
Chris@0:      * Returns the value at which validation was started in the object graph.
Chris@0:      *
Chris@0:      * The validator, when given an object, traverses the properties and
Chris@0:      * related objects and their properties. The root of the validation is the
Chris@0:      * object from which the traversal started.
Chris@0:      *
Chris@0:      * The current value is returned by {@link getValue}.
Chris@0:      *
Chris@0:      * @return mixed The root value of the validation
Chris@0:      */
Chris@0:     public function getRoot();
Chris@0: 
Chris@0:     /**
Chris@0:      * Returns the value that the validator is currently validating.
Chris@0:      *
Chris@0:      * If you want to retrieve the object that was originally passed to the
Chris@0:      * validator, use {@link getRoot}.
Chris@0:      *
Chris@0:      * @return mixed The currently validated value
Chris@0:      */
Chris@0:     public function getValue();
Chris@0: 
Chris@0:     /**
Chris@0:      * Returns the metadata for the currently validated value.
Chris@0:      *
Chris@0:      * With the core implementation, this method returns a
Chris@0:      * {@link Mapping\ClassMetadataInterface} instance if the current value is an object,
Chris@0:      * a {@link Mapping\PropertyMetadata} instance if the current value is
Chris@0:      * the value of a property and a {@link Mapping\GetterMetadata} instance if
Chris@0:      * the validated value is the result of a getter method.
Chris@0:      *
Chris@0:      * If the validated value is neither of these, for example if the validator
Chris@0:      * has been called with a plain value and constraint, this method returns
Chris@0:      * null.
Chris@0:      *
Chris@14:      * @return MetadataInterface|null the metadata of the currently validated
Chris@14:      *                                value
Chris@0:      */
Chris@0:     public function getMetadata();
Chris@0: 
Chris@0:     /**
Chris@0:      * Returns the validation group that is currently being validated.
Chris@0:      *
Chris@0:      * @return string The current validation group
Chris@0:      */
Chris@0:     public function getGroup();
Chris@0: 
Chris@0:     /**
Chris@0:      * Returns the class name of the current node.
Chris@0:      *
Chris@0:      * If the metadata of the current node does not implement
Chris@0:      * {@link Mapping\ClassMetadataInterface} or if no metadata is available for the
Chris@0:      * current node, this method returns null.
Chris@0:      *
Chris@0:      * @return string|null The class name or null, if no class name could be found
Chris@0:      */
Chris@0:     public function getClassName();
Chris@0: 
Chris@0:     /**
Chris@0:      * Returns the property name of the current node.
Chris@0:      *
Chris@0:      * If the metadata of the current node does not implement
Chris@0:      * {@link PropertyMetadataInterface} or if no metadata is available for the
Chris@0:      * current node, this method returns null.
Chris@0:      *
Chris@0:      * @return string|null The property name or null, if no property name could be found
Chris@0:      */
Chris@0:     public function getPropertyName();
Chris@0: 
Chris@0:     /**
Chris@0:      * Returns the property path to the value that the validator is currently
Chris@0:      * validating.
Chris@0:      *
Chris@0:      * For example, take the following object graph:
Chris@0:      *
Chris@0:      * <pre>
Chris@0:      * (Person)---($address: Address)---($street: string)
Chris@0:      * </pre>
Chris@0:      *
Chris@0:      * When the <tt>Person</tt> instance is passed to the validator, the
Chris@0:      * property path is initially empty. When the <tt>$address</tt> property
Chris@0:      * of that person is validated, the property path is "address". When
Chris@0:      * the <tt>$street</tt> property of the related <tt>Address</tt> instance
Chris@0:      * is validated, the property path is "address.street".
Chris@0:      *
Chris@0:      * Properties of objects are prefixed with a dot in the property path.
Chris@0:      * Indices of arrays or objects implementing the {@link \ArrayAccess}
Chris@0:      * interface are enclosed in brackets. For example, if the property in
Chris@0:      * the previous example is <tt>$addresses</tt> and contains an array
Chris@0:      * of <tt>Address</tt> instance, the property path generated for the
Chris@0:      * <tt>$street</tt> property of one of these addresses is for example
Chris@0:      * "addresses[0].street".
Chris@0:      *
Chris@0:      * @param string $subPath Optional. The suffix appended to the current
Chris@0:      *                        property path.
Chris@0:      *
Chris@0:      * @return string The current property path. The result may be an empty
Chris@0:      *                string if the validator is currently validating the
Chris@0:      *                root value of the validation graph.
Chris@0:      */
Chris@0:     public function getPropertyPath($subPath = '');
Chris@0: }