annotate vendor/symfony/validator/Context/ExecutionContextInterface.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 129ea1e6d783
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 /*
Chris@0 4 * This file is part of the Symfony package.
Chris@0 5 *
Chris@0 6 * (c) Fabien Potencier <fabien@symfony.com>
Chris@0 7 *
Chris@0 8 * For the full copyright and license information, please view the LICENSE
Chris@0 9 * file that was distributed with this source code.
Chris@0 10 */
Chris@0 11
Chris@0 12 namespace Symfony\Component\Validator\Context;
Chris@0 13
Chris@0 14 use Symfony\Component\Validator\Constraint;
Chris@17 15 use Symfony\Component\Validator\ConstraintViolationListInterface;
Chris@0 16 use Symfony\Component\Validator\Mapping;
Chris@0 17 use Symfony\Component\Validator\Mapping\MetadataInterface;
Chris@0 18 use Symfony\Component\Validator\Validator\ValidatorInterface;
Chris@0 19 use Symfony\Component\Validator\Violation\ConstraintViolationBuilderInterface;
Chris@0 20
Chris@0 21 /**
Chris@0 22 * The context of a validation run.
Chris@0 23 *
Chris@0 24 * The context collects all violations generated during the validation. By
Chris@0 25 * default, validators execute all validations in a new context:
Chris@0 26 *
Chris@0 27 * $violations = $validator->validate($object);
Chris@0 28 *
Chris@0 29 * When you make another call to the validator, while the validation is in
Chris@0 30 * progress, the violations will be isolated from each other:
Chris@0 31 *
Chris@0 32 * public function validate($value, Constraint $constraint)
Chris@0 33 * {
Chris@0 34 * $validator = $this->context->getValidator();
Chris@0 35 *
Chris@0 36 * // The violations are not added to $this->context
Chris@0 37 * $violations = $validator->validate($value);
Chris@0 38 * }
Chris@0 39 *
Chris@0 40 * However, if you want to add the violations to the current context, use the
Chris@0 41 * {@link ValidatorInterface::inContext()} method:
Chris@0 42 *
Chris@0 43 * public function validate($value, Constraint $constraint)
Chris@0 44 * {
Chris@0 45 * $validator = $this->context->getValidator();
Chris@0 46 *
Chris@0 47 * // The violations are added to $this->context
Chris@0 48 * $validator
Chris@0 49 * ->inContext($this->context)
Chris@0 50 * ->validate($value)
Chris@0 51 * ;
Chris@0 52 * }
Chris@0 53 *
Chris@0 54 * Additionally, the context provides information about the current state of
Chris@0 55 * the validator, such as the currently validated class, the name of the
Chris@0 56 * currently validated property and more. These values change over time, so you
Chris@0 57 * cannot store a context and expect that the methods still return the same
Chris@0 58 * results later on.
Chris@0 59 *
Chris@0 60 * @author Bernhard Schussek <bschussek@gmail.com>
Chris@0 61 */
Chris@0 62 interface ExecutionContextInterface
Chris@0 63 {
Chris@0 64 /**
Chris@0 65 * Adds a violation at the current node of the validation graph.
Chris@0 66 *
Chris@0 67 * @param string $message The error message
Chris@0 68 * @param array $params The parameters substituted in the error message
Chris@0 69 */
Chris@17 70 public function addViolation($message, array $params = []);
Chris@0 71
Chris@0 72 /**
Chris@0 73 * Returns a builder for adding a violation with extended information.
Chris@0 74 *
Chris@0 75 * Call {@link ConstraintViolationBuilderInterface::addViolation()} to
Chris@0 76 * add the violation when you're done with the configuration:
Chris@0 77 *
Chris@0 78 * $context->buildViolation('Please enter a number between %min% and %max%.')
Chris@0 79 * ->setParameter('%min%', 3)
Chris@0 80 * ->setParameter('%max%', 10)
Chris@0 81 * ->setTranslationDomain('number_validation')
Chris@0 82 * ->addViolation();
Chris@0 83 *
Chris@0 84 * @param string $message The error message
Chris@0 85 * @param array $parameters The parameters substituted in the error message
Chris@0 86 *
Chris@0 87 * @return ConstraintViolationBuilderInterface The violation builder
Chris@0 88 */
Chris@17 89 public function buildViolation($message, array $parameters = []);
Chris@0 90
Chris@0 91 /**
Chris@0 92 * Returns the validator.
Chris@0 93 *
Chris@0 94 * Useful if you want to validate additional constraints:
Chris@0 95 *
Chris@0 96 * public function validate($value, Constraint $constraint)
Chris@0 97 * {
Chris@0 98 * $validator = $this->context->getValidator();
Chris@0 99 *
Chris@17 100 * $violations = $validator->validate($value, new Length(['min' => 3]));
Chris@0 101 *
Chris@0 102 * if (count($violations) > 0) {
Chris@0 103 * // ...
Chris@0 104 * }
Chris@0 105 * }
Chris@0 106 *
Chris@0 107 * @return ValidatorInterface
Chris@0 108 */
Chris@0 109 public function getValidator();
Chris@0 110
Chris@0 111 /**
Chris@0 112 * Returns the currently validated object.
Chris@0 113 *
Chris@0 114 * If the validator is currently validating a class constraint, the
Chris@17 115 * object of that class is returned. If it is validating a property or
Chris@0 116 * getter constraint, the object that the property/getter belongs to is
Chris@0 117 * returned.
Chris@0 118 *
Chris@0 119 * In other cases, null is returned.
Chris@0 120 *
Chris@0 121 * @return object|null The currently validated object or null
Chris@0 122 */
Chris@0 123 public function getObject();
Chris@0 124
Chris@0 125 /**
Chris@0 126 * Sets the currently validated value.
Chris@0 127 *
Chris@0 128 * @param mixed $value The validated value
Chris@0 129 * @param object|null $object The currently validated object
Chris@0 130 * @param MetadataInterface|null $metadata The validation metadata
Chris@0 131 * @param string $propertyPath The property path to the current value
Chris@0 132 *
Chris@0 133 * @internal Used by the validator engine. Should not be called by user
Chris@0 134 * code.
Chris@0 135 */
Chris@0 136 public function setNode($value, $object, MetadataInterface $metadata = null, $propertyPath);
Chris@0 137
Chris@0 138 /**
Chris@0 139 * Sets the currently validated group.
Chris@0 140 *
Chris@0 141 * @param string|null $group The validated group
Chris@0 142 *
Chris@0 143 * @internal Used by the validator engine. Should not be called by user
Chris@0 144 * code.
Chris@0 145 */
Chris@0 146 public function setGroup($group);
Chris@0 147
Chris@0 148 /**
Chris@0 149 * Sets the currently validated constraint.
Chris@0 150 *
Chris@0 151 * @param Constraint $constraint The validated constraint
Chris@0 152 *
Chris@0 153 * @internal Used by the validator engine. Should not be called by user
Chris@0 154 * code.
Chris@0 155 */
Chris@0 156 public function setConstraint(Constraint $constraint);
Chris@0 157
Chris@0 158 /**
Chris@0 159 * Marks an object as validated in a specific validation group.
Chris@0 160 *
Chris@0 161 * @param string $cacheKey The hash of the object
Chris@0 162 * @param string $groupHash The group's name or hash, if it is group
Chris@0 163 * sequence
Chris@0 164 *
Chris@0 165 * @internal Used by the validator engine. Should not be called by user
Chris@0 166 * code.
Chris@0 167 */
Chris@0 168 public function markGroupAsValidated($cacheKey, $groupHash);
Chris@0 169
Chris@0 170 /**
Chris@0 171 * Returns whether an object was validated in a specific validation group.
Chris@0 172 *
Chris@0 173 * @param string $cacheKey The hash of the object
Chris@0 174 * @param string $groupHash The group's name or hash, if it is group
Chris@0 175 * sequence
Chris@0 176 *
Chris@0 177 * @return bool Whether the object was already validated for that
Chris@0 178 * group
Chris@0 179 *
Chris@0 180 * @internal Used by the validator engine. Should not be called by user
Chris@0 181 * code.
Chris@0 182 */
Chris@0 183 public function isGroupValidated($cacheKey, $groupHash);
Chris@0 184
Chris@0 185 /**
Chris@0 186 * Marks a constraint as validated for an object.
Chris@0 187 *
Chris@0 188 * @param string $cacheKey The hash of the object
Chris@0 189 * @param string $constraintHash The hash of the constraint
Chris@0 190 *
Chris@0 191 * @internal Used by the validator engine. Should not be called by user
Chris@0 192 * code.
Chris@0 193 */
Chris@0 194 public function markConstraintAsValidated($cacheKey, $constraintHash);
Chris@0 195
Chris@0 196 /**
Chris@0 197 * Returns whether a constraint was validated for an object.
Chris@0 198 *
Chris@0 199 * @param string $cacheKey The hash of the object
Chris@0 200 * @param string $constraintHash The hash of the constraint
Chris@0 201 *
Chris@0 202 * @return bool Whether the constraint was already validated
Chris@0 203 *
Chris@0 204 * @internal Used by the validator engine. Should not be called by user
Chris@0 205 * code.
Chris@0 206 */
Chris@0 207 public function isConstraintValidated($cacheKey, $constraintHash);
Chris@0 208
Chris@0 209 /**
Chris@0 210 * Marks that an object was initialized.
Chris@0 211 *
Chris@0 212 * @param string $cacheKey The hash of the object
Chris@0 213 *
Chris@0 214 * @internal Used by the validator engine. Should not be called by user
Chris@0 215 * code.
Chris@0 216 *
Chris@0 217 * @see ObjectInitializerInterface
Chris@0 218 */
Chris@0 219 public function markObjectAsInitialized($cacheKey);
Chris@0 220
Chris@0 221 /**
Chris@0 222 * Returns whether an object was initialized.
Chris@0 223 *
Chris@0 224 * @param string $cacheKey The hash of the object
Chris@0 225 *
Chris@0 226 * @return bool Whether the object was already initialized
Chris@0 227 *
Chris@0 228 * @internal Used by the validator engine. Should not be called by user
Chris@0 229 * code.
Chris@0 230 *
Chris@0 231 * @see ObjectInitializerInterface
Chris@0 232 */
Chris@0 233 public function isObjectInitialized($cacheKey);
Chris@0 234
Chris@0 235 /**
Chris@0 236 * Returns the violations generated by the validator so far.
Chris@0 237 *
Chris@0 238 * @return ConstraintViolationListInterface The constraint violation list
Chris@0 239 */
Chris@0 240 public function getViolations();
Chris@0 241
Chris@0 242 /**
Chris@0 243 * Returns the value at which validation was started in the object graph.
Chris@0 244 *
Chris@0 245 * The validator, when given an object, traverses the properties and
Chris@0 246 * related objects and their properties. The root of the validation is the
Chris@0 247 * object from which the traversal started.
Chris@0 248 *
Chris@0 249 * The current value is returned by {@link getValue}.
Chris@0 250 *
Chris@0 251 * @return mixed The root value of the validation
Chris@0 252 */
Chris@0 253 public function getRoot();
Chris@0 254
Chris@0 255 /**
Chris@0 256 * Returns the value that the validator is currently validating.
Chris@0 257 *
Chris@0 258 * If you want to retrieve the object that was originally passed to the
Chris@0 259 * validator, use {@link getRoot}.
Chris@0 260 *
Chris@0 261 * @return mixed The currently validated value
Chris@0 262 */
Chris@0 263 public function getValue();
Chris@0 264
Chris@0 265 /**
Chris@0 266 * Returns the metadata for the currently validated value.
Chris@0 267 *
Chris@0 268 * With the core implementation, this method returns a
Chris@0 269 * {@link Mapping\ClassMetadataInterface} instance if the current value is an object,
Chris@0 270 * a {@link Mapping\PropertyMetadata} instance if the current value is
Chris@0 271 * the value of a property and a {@link Mapping\GetterMetadata} instance if
Chris@0 272 * the validated value is the result of a getter method.
Chris@0 273 *
Chris@0 274 * If the validated value is neither of these, for example if the validator
Chris@0 275 * has been called with a plain value and constraint, this method returns
Chris@0 276 * null.
Chris@0 277 *
Chris@14 278 * @return MetadataInterface|null the metadata of the currently validated
Chris@14 279 * value
Chris@0 280 */
Chris@0 281 public function getMetadata();
Chris@0 282
Chris@0 283 /**
Chris@0 284 * Returns the validation group that is currently being validated.
Chris@0 285 *
Chris@0 286 * @return string The current validation group
Chris@0 287 */
Chris@0 288 public function getGroup();
Chris@0 289
Chris@0 290 /**
Chris@0 291 * Returns the class name of the current node.
Chris@0 292 *
Chris@0 293 * If the metadata of the current node does not implement
Chris@0 294 * {@link Mapping\ClassMetadataInterface} or if no metadata is available for the
Chris@0 295 * current node, this method returns null.
Chris@0 296 *
Chris@0 297 * @return string|null The class name or null, if no class name could be found
Chris@0 298 */
Chris@0 299 public function getClassName();
Chris@0 300
Chris@0 301 /**
Chris@0 302 * Returns the property name of the current node.
Chris@0 303 *
Chris@0 304 * If the metadata of the current node does not implement
Chris@0 305 * {@link PropertyMetadataInterface} or if no metadata is available for the
Chris@0 306 * current node, this method returns null.
Chris@0 307 *
Chris@0 308 * @return string|null The property name or null, if no property name could be found
Chris@0 309 */
Chris@0 310 public function getPropertyName();
Chris@0 311
Chris@0 312 /**
Chris@0 313 * Returns the property path to the value that the validator is currently
Chris@0 314 * validating.
Chris@0 315 *
Chris@0 316 * For example, take the following object graph:
Chris@0 317 *
Chris@0 318 * <pre>
Chris@0 319 * (Person)---($address: Address)---($street: string)
Chris@0 320 * </pre>
Chris@0 321 *
Chris@0 322 * When the <tt>Person</tt> instance is passed to the validator, the
Chris@0 323 * property path is initially empty. When the <tt>$address</tt> property
Chris@0 324 * of that person is validated, the property path is "address". When
Chris@0 325 * the <tt>$street</tt> property of the related <tt>Address</tt> instance
Chris@0 326 * is validated, the property path is "address.street".
Chris@0 327 *
Chris@0 328 * Properties of objects are prefixed with a dot in the property path.
Chris@0 329 * Indices of arrays or objects implementing the {@link \ArrayAccess}
Chris@0 330 * interface are enclosed in brackets. For example, if the property in
Chris@0 331 * the previous example is <tt>$addresses</tt> and contains an array
Chris@0 332 * of <tt>Address</tt> instance, the property path generated for the
Chris@0 333 * <tt>$street</tt> property of one of these addresses is for example
Chris@0 334 * "addresses[0].street".
Chris@0 335 *
Chris@0 336 * @param string $subPath Optional. The suffix appended to the current
Chris@0 337 * property path.
Chris@0 338 *
Chris@0 339 * @return string The current property path. The result may be an empty
Chris@0 340 * string if the validator is currently validating the
Chris@0 341 * root value of the validation graph.
Chris@0 342 */
Chris@0 343 public function getPropertyPath($subPath = '');
Chris@0 344 }