forked from symfony/validator
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathExecutionContextInterface.php
329 lines (314 loc) · 13.3 KB
/
ExecutionContextInterface.php
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
<?php
/*
* This file is part of the Symfony package.
*
* (c) Fabien Potencier <[email protected]>
*
* 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 <[email protected]>
*
* @api
*
* @deprecated Deprecated since version 2.5, to be removed in Symfony 3.0.
* Use {@link Context\ExecutionContextInterface} instead.
*/
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 $plural The number to use to pluralize of the message
* @param integer|null $code The violation code
*
* @api
*
* @deprecated The parameters $invalidValue, $pluralization and $code are
* deprecated since version 2.5 and will be removed in
* Symfony 3.0.
*/
public function addViolation($message, array $params = array(), $invalidValue = null, $plural = 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 $parameters The parameters substituted in the error message
* @param mixed $invalidValue The invalid, validated value
* @param integer|null $plural The number to use to pluralize of the message
* @param integer|null $code The violation code
*
* @api
*
* @deprecated Deprecated since version 2.5, to be removed in Symfony 3.0.
* Use {@link Context\ExecutionContextInterface::buildViolation()}
* instead.
*/
public function addViolationAt($subPath, $message, array $parameters = array(), $invalidValue = null, $plural = 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.
*
* @deprecated Deprecated since version 2.5, to be removed in Symfony 3.0.
* Use {@link Context\ExecutionContextInterface::getValidator()}
* instead.
*/
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.
*
* @deprecated Deprecated since version 2.5, to be removed in Symfony 3.0.
* Use {@link Context\ExecutionContextInterface::getValidator()}
* instead.
*/
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.
*
* @deprecated Deprecated since version 2.5, to be removed in Symfony 3.0.
* Use {@link Context\ExecutionContextInterface::getValidator()}
* instead and call
* {@link Validator\ValidatorInterface::getMetadataFor()} or
* {@link Validator\ValidatorInterface::hasMetadataFor()} there.
*/
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 = '');
}