ExecutionContextInterface.php

<?php

/*
 * This file is part of the Symfony package.
 *
 * (c) Fabien Potencier <fabien@symfony.com>
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */
namespace Symfony\Component\Validator;


/**
 * Stores the validator's state during validation.
 *
 * For example, let's validate the following object graph:
 *
 * <pre>
 * (Person)---($firstName: string)
 *      \
 *   ($address: Address)---($street: string)
 * </pre>
 *
 * We validate the <tt>Person</tt> instance, which becomes the "root" of the
 * validation run (see {@link getRoot}). The state of the context after the
 * first step will be like this:
 *
 * <pre>
 * (Person)---($firstName: string)
 *    ^ \
 *   ($address: Address)---($street: string)
 * </pre>
 *
 * The validator is stopped at the <tt>Person</tt> node, both the root and the
 * value (see {@link getValue}) of the context point to the <tt>Person</tt>
 * instance. The property path is empty at this point (see {@link getPropertyPath}).
 * The metadata of the context is the metadata of the <tt>Person</tt> node
 * (see {@link getMetadata}).
 *
 * After advancing to the property <tt>$firstName</tt> of the <tt>Person</tt>
 * instance, the state of the context looks like this:
 *
 * <pre>
 * (Person)---($firstName: string)
 *      \              ^
 *   ($address: Address)---($street: string)
 * </pre>
 *
 * The validator is stopped at the property <tt>$firstName</tt>. The root still
 * points to the <tt>Person</tt> instance, because this is where the validation
 * started. The property path is now "firstName" and the current value is the
 * value of that property.
 *
 * After advancing to the <tt>$address</tt> property and then to the
 * <tt>$street</tt> property of the <tt>Address</tt> instance, the context state
 * looks like this:
 *
 * <pre>
 * (Person)---($firstName: string)
 *      \
 *   ($address: Address)---($street: string)
 *                               ^
 * </pre>
 *
 * The validator is stopped at the property <tt>$street</tt>. The root still
 * points to the <tt>Person</tt> instance, but the property path is now
 * "address.street" and the validated value is the value of that property.
 *
 * Apart from the root, the property path and the currently validated value,
 * the execution context also knows the metadata of the current node (see
 * {@link getMetadata}) which for example returns a {@link Mapping\PropertyMetadata}
 * or a {@link Mapping\ClassMetadata} object. he context also contains the
 * validation group that is currently being validated (see {@link getGroup}) and
 * the violations that happened up until now (see {@link getViolations}).
 *
 * Apart from reading the execution context, you can also use
 * {@link addViolation} or {@link addViolationAt} to add new violations and
 * {@link validate} or {@link validateValue} to validate values that the
 * validator otherwise would not reach.
 *
 * @author Bernhard Schussek <bschussek@gmail.com>
 *
 * @api
 */
interface ExecutionContextInterface {

  /**
   * Adds a violation at the current node of the validation graph.
   *
   * @param string       $message       The error message.
   * @param array        $params        The parameters substituted in the error message.
   * @param mixed        $invalidValue  The invalid, validated value.
   * @param integer|null $pluralization The number to use to pluralize of the message.
   * @param integer|null $code          The violation code.
   *
   * @api
   */
  public function addViolation($message, array $params = array(), $invalidValue = null, $pluralization = null, $code = null);

  /**
   * Adds a violation at the validation graph node with the given property
   * path relative to the current property path.
   *
   * @param string       $subPath       The relative property path for the violation.
   * @param string       $message       The error message.
   * @param array        $params        The parameters substituted in the error message.
   * @param mixed        $invalidValue  The invalid, validated value.
   * @param integer|null $pluralization The number to use to pluralize of the message.
   * @param integer|null $code          The violation code.
   *
   * @api
   */
  public function addViolationAt($subPath, $message, array $params = array(), $invalidValue = null, $pluralization = null, $code = null);

  /**
   * Validates the given value within the scope of the current validation.
   *
   * The value may be any value recognized by the used metadata factory
   * (see {@link MetadataFactoryInterface::getMetadata}), or an array or a
   * traversable object of such values.
   *
   * Usually you validate a value that is not the current node of the
   * execution context. For this case, you can pass the {@link $subPath}
   * argument which is appended to the current property path when a violation
   * is created. For example, take the following object graph:
   *
   * <pre>
   * (Person)---($address: Address)---($phoneNumber: PhoneNumber)
   *                     ^
   * </pre>
   *
   * When the execution context stops at the <tt>Person</tt> instance, the
   * property path is "address". When you validate the <tt>PhoneNumber</tt>
   * instance now, pass "phoneNumber" as sub path to correct the property path
   * to "address.phoneNumber":
   *
   * <pre>
   * $context->validate($address->phoneNumber, 'phoneNumber');
   * </pre>
   *
   * Any violations generated during the validation will be added to the
   * violation list that you can access with {@link getViolations}.
   *
   * @param mixed                $value    The value to validate.
   * @param string               $subPath  The path to append to the context's property path.
   * @param null|string|string[] $groups   The groups to validate in. If you don't pass any
   *                                       groups here, the current group of the context
   *                                       will be used.
   * @param Boolean              $traverse Whether to traverse the value if it is an array
   *                                       or an instance of <tt>\Traversable</tt>.
   * @param Boolean              $deep     Whether to traverse the value recursively if
   *                                       it is a collection of collections.
   */
  public function validate($value, $subPath = '', $groups = null, $traverse = false, $deep = false);

  /**
   * Validates a value against a constraint.
   *
   * Use the parameter <tt>$subPath</tt> to adapt the property path for the
   * validated value. For example, take the following object graph:
   *
   * <pre>
   * (Person)---($address: Address)---($street: string)
   *                     ^
   * </pre>
   *
   * When the validator validates the <tt>Address</tt> instance, the
   * property path stored in the execution context is "address". When you
   * manually validate the property <tt>$street</tt> now, pass the sub path
   * "street" to adapt the full property path to "address.street":
   *
   * <pre>
   * $context->validate($address->street, new NotNull(), 'street');
   * </pre>
   *
   * @param mixed                   $value       The value to validate.
   * @param Constraint|Constraint[] $constraints The constraint(s) to validate against.
   * @param string                  $subPath     The path to append to the context's property path.
   * @param null|string|string[]    $groups      The groups to validate in. If you don't pass any
   *                                             groups here, the current group of the context
   *                                             will be used.
   */
  public function validateValue($value, $constraints, $subPath = '', $groups = null);

  /**
   * Returns the violations generated by the validator so far.
   *
   * @return ConstraintViolationListInterface The constraint violation list.
   *
   * @api
   */
  public function getViolations();

  /**
   * Returns the value at which validation was started in the object graph.
   *
   * The validator, when given an object, traverses the properties and
   * related objects and their properties. The root of the validation is the
   * object from which the traversal started.
   *
   * The current value is returned by {@link getValue}.
   *
   * @return mixed The root value of the validation.
   */
  public function getRoot();

  /**
   * Returns the value that the validator is currently validating.
   *
   * If you want to retrieve the object that was originally passed to the
   * validator, use {@link getRoot}.
   *
   * @return mixed The currently validated value.
   */
  public function getValue();

  /**
   * Returns the metadata for the currently validated value.
   *
   * With the core implementation, this method returns a
   * {@link Mapping\ClassMetadata} instance if the current value is an object,
   * a {@link Mapping\PropertyMetadata} instance if the current value is
   * the value of a property and a {@link Mapping\GetterMetadata} instance if
   * the validated value is the result of a getter method.
   *
   * If the validated value is neither of these, for example if the validator
   * has been called with a plain value and constraint, this method returns
   * null.
   *
   * @return MetadataInterface|null The metadata of the currently validated
   *                                value.
   */
  public function getMetadata();

  /**
   * Returns the used metadata factory.
   *
   * @return MetadataFactoryInterface The metadata factory.
   */
  public function getMetadataFactory();

  /**
   * Returns the validation group that is currently being validated.
   *
   * @return string The current validation group.
   */
  public function getGroup();

  /**
   * Returns the class name of the current node.
   *
   * If the metadata of the current node does not implement
   * {@link ClassBasedInterface} or if no metadata is available for the
   * current node, this method returns null.
   *
   * @return string|null The class name or null, if no class name could be found.
   */
  public function getClassName();

  /**
   * Returns the property name of the current node.
   *
   * If the metadata of the current node does not implement
   * {@link PropertyMetadataInterface} or if no metadata is available for the
   * current node, this method returns null.
   *
   * @return string|null The property name or null, if no property name could be found.
   */
  public function getPropertyName();

  /**
   * Returns the property path to the value that the validator is currently
   * validating.
   *
   * For example, take the following object graph:
   *
   * <pre>
   * (Person)---($address: Address)---($street: string)
   * </pre>
   *
   * When the <tt>Person</tt> instance is passed to the validator, the
   * property path is initially empty. When the <tt>$address</tt> property
   * of that person is validated, the property path is "address". When
   * the <tt>$street</tt> property of the related <tt>Address</tt> instance
   * is validated, the property path is "address.street".
   *
   * Properties of objects are prefixed with a dot in the property path.
   * Indices of arrays or objects implementing the {@link \ArrayAccess}
   * interface are enclosed in brackets. For example, if the property in
   * the previous example is <tt>$addresses</tt> and contains an array
   * of <tt>Address</tt> instance, the property path generated for the
   * <tt>$street</tt> property of one of these addresses is for example
   * "addresses[0].street".
   *
   * @param string $subPath Optional. The suffix appended to the current
   *                        property path.
   *
   * @return string The current property path. The result may be an empty
   *                string if the validator is currently validating the
   *                root value of the validation graph.
   */
  public function getPropertyPath($subPath = '');

}