www.aleph1.co.uk Git - yaffs-website/blob - vendor/symfony/validator/ExecutionContextInterface.php

   1 <?php
   2
   3 /*
   4  * This file is part of the Symfony package.
   5  *
   6  * (c) Fabien Potencier <fabien@symfony.com>
   7  *
   8  * For the full copyright and license information, please view the LICENSE
   9  * file that was distributed with this source code.
  10  */
  11
  12 namespace Symfony\Component\Validator;
  13
  14 /**
  15  * Stores the validator's state during validation.
  16  *
  17  * For example, let's validate the following object graph:
  18  *
  19  * <pre>
  20  * (Person)---($firstName: string)
  21  *      \
  22  *   ($address: Address)---($street: string)
  23  * </pre>
  24  *
  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:
  28  *
  29  * <pre>
  30  * (Person)---($firstName: string)
  31  *    ^ \
  32  *   ($address: Address)---($street: string)
  33  * </pre>
  34  *
  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}).
  40  *
  41  * After advancing to the property <tt>$firstName</tt> of the <tt>Person</tt>
  42  * instance, the state of the context looks like this:
  43  *
  44  * <pre>
  45  * (Person)---($firstName: string)
  46  *      \              ^
  47  *   ($address: Address)---($street: string)
  48  * </pre>
  49  *
  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.
  54  *
  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
  57  * looks like this:
  58  *
  59  * <pre>
  60  * (Person)---($firstName: string)
  61  *      \
  62  *   ($address: Address)---($street: string)
  63  *                               ^
  64  * </pre>
  65  *
  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.
  69  *
  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}).
  76  *
  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.
  81  *
  82  * @author Bernhard Schussek <bschussek@gmail.com>
  83  *
  84  * @deprecated since version 2.5, to be removed in 3.0.
  85  *             Use {@link Context\ExecutionContextInterface} instead.
  86  */
  87 interface ExecutionContextInterface
  88 {
  89     /**
  90      * Adds a violation at the current node of the validation graph.
  91      *
  92      * Note: the parameters $invalidValue, $plural and $code are deprecated since version 2.5 and will be removed in 3.0.
  93      *
  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
  99      */
 100     public function addViolation($message, array $params = array(), $invalidValue = null, $plural = null, $code = null);
 101
 102     /**
 103      * Adds a violation at the validation graph node with the given property
 104      * path relative to the current property path.
 105      *
 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
 112      *
 113      * @deprecated since version 2.5, to be removed in 3.0.
 114      *             Use {@link Context\ExecutionContextInterface::buildViolation()}
 115      *             instead.
 116      */
 117     public function addViolationAt($subPath, $message, array $parameters = array(), $invalidValue = null, $plural = null, $code = null);
 118
 119     /**
 120      * Validates the given value within the scope of the current validation.
 121      *
 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.
 125      *
 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:
 130      *
 131      * <pre>
 132      * (Person)---($address: Address)---($phoneNumber: PhoneNumber)
 133      *                     ^
 134      * </pre>
 135      *
 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":
 140      *
 141      * <pre>
 142      * $context->validate($address->phoneNumber, 'phoneNumber');
 143      * </pre>
 144      *
 145      * Any violations generated during the validation will be added to the
 146      * violation list that you can access with {@link getViolations}.
 147      *
 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
 152      *                                       will be used.
 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.
 157      *
 158      * @deprecated since version 2.5, to be removed in 3.0.
 159      *             Use {@link Context\ExecutionContextInterface::getValidator()}
 160      *             instead.
 161      */
 162     public function validate($value, $subPath = '', $groups = null, $traverse = false, $deep = false);
 163
 164     /**
 165      * Validates a value against a constraint.
 166      *
 167      * Use the parameter <tt>$subPath</tt> to adapt the property path for the
 168      * validated value. For example, take the following object graph:
 169      *
 170      * <pre>
 171      * (Person)---($address: Address)---($street: string)
 172      *                     ^
 173      * </pre>
 174      *
 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":
 179      *
 180      * <pre>
 181      * $context->validate($address->street, new NotNull(), 'street');
 182      * </pre>
 183      *
 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
 189      *                                             will be used.
 190      *
 191      * @deprecated since version 2.5, to be removed in 3.0.
 192      *             Use {@link Context\ExecutionContextInterface::getValidator()}
 193      *             instead.
 194      */
 195     public function validateValue($value, $constraints, $subPath = '', $groups = null);
 196
 197     /**
 198      * Returns the violations generated by the validator so far.
 199      *
 200      * @return ConstraintViolationListInterface The constraint violation list
 201      */
 202     public function getViolations();
 203
 204     /**
 205      * Returns the value at which validation was started in the object graph.
 206      *
 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.
 210      *
 211      * The current value is returned by {@link getValue}.
 212      *
 213      * @return mixed The root value of the validation
 214      */
 215     public function getRoot();
 216
 217     /**
 218      * Returns the value that the validator is currently validating.
 219      *
 220      * If you want to retrieve the object that was originally passed to the
 221      * validator, use {@link getRoot}.
 222      *
 223      * @return mixed The currently validated value
 224      */
 225     public function getValue();
 226
 227     /**
 228      * Returns the metadata for the currently validated value.
 229      *
 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.
 235      *
 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
 238      * null.
 239      *
 240      * @return MetadataInterface|null The metadata of the currently validated
 241      *                                value.
 242      */
 243     public function getMetadata();
 244
 245     /**
 246      * Returns the used metadata factory.
 247      *
 248      * @return MetadataFactoryInterface The metadata factory
 249      *
 250      * @deprecated since version 2.5, to be removed in 3.0.
 251      *             Use {@link Context\ExecutionContextInterface::getValidator()}
 252      *             instead and call
 253      *             {@link Validator\ValidatorInterface::getMetadataFor()} or
 254      *             {@link Validator\ValidatorInterface::hasMetadataFor()} there.
 255      */
 256     public function getMetadataFactory();
 257
 258     /**
 259      * Returns the validation group that is currently being validated.
 260      *
 261      * @return string The current validation group
 262      */
 263     public function getGroup();
 264
 265     /**
 266      * Returns the class name of the current node.
 267      *
 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.
 271      *
 272      * @return string|null The class name or null, if no class name could be found
 273      */
 274     public function getClassName();
 275
 276     /**
 277      * Returns the property name of the current node.
 278      *
 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.
 282      *
 283      * @return string|null The property name or null, if no property name could be found
 284      */
 285     public function getPropertyName();
 286
 287     /**
 288      * Returns the property path to the value that the validator is currently
 289      * validating.
 290      *
 291      * For example, take the following object graph:
 292      *
 293      * <pre>
 294      * (Person)---($address: Address)---($street: string)
 295      * </pre>
 296      *
 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".
 302      *
 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".
 310      *
 311      * @param string $subPath Optional. The suffix appended to the current
 312      *                        property path.
 313      *
 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.
 317      */
 318     public function getPropertyPath($subPath = '');
 319 }