ExecutionContextInterface.php 12 KB

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