]>
Commit | Line | Data |
---|---|---|
4f5b44bd NL |
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\Form; | |
13 | ||
14 | /** | |
15 | * A form group bundling multiple forms in a hierarchical structure. | |
16 | * | |
17 | * @author Bernhard Schussek <bschussek@gmail.com> | |
18 | */ | |
19 | interface FormInterface extends \ArrayAccess, \Traversable, \Countable | |
20 | { | |
21 | /** | |
22 | * Sets the parent form. | |
23 | * | |
24 | * @param FormInterface|null $parent The parent form or null if it's the root. | |
25 | * | |
26 | * @return FormInterface The form instance | |
27 | * | |
28 | * @throws Exception\AlreadySubmittedException If the form has already been submitted. | |
29 | * @throws Exception\LogicException When trying to set a parent for a form with | |
30 | * an empty name. | |
31 | */ | |
32 | public function setParent(FormInterface $parent = null); | |
33 | ||
34 | /** | |
35 | * Returns the parent form. | |
36 | * | |
37 | * @return FormInterface|null The parent form or null if there is none. | |
38 | */ | |
39 | public function getParent(); | |
40 | ||
41 | /** | |
42 | * Adds a child to the form. | |
43 | * | |
44 | * @param FormInterface|string|integer $child The FormInterface instance or the name of the child. | |
45 | * @param string|null $type The child's type, if a name was passed. | |
46 | * @param array $options The child's options, if a name was passed. | |
47 | * | |
48 | * @return FormInterface The form instance | |
49 | * | |
50 | * @throws Exception\AlreadySubmittedException If the form has already been submitted. | |
51 | * @throws Exception\LogicException When trying to add a child to a non-compound form. | |
52 | * @throws Exception\UnexpectedTypeException If $child or $type has an unexpected type. | |
53 | */ | |
54 | public function add($child, $type = null, array $options = array()); | |
55 | ||
56 | /** | |
57 | * Returns the child with the given name. | |
58 | * | |
59 | * @param string $name The name of the child | |
60 | * | |
61 | * @return FormInterface The child form | |
62 | * | |
63 | * @throws \OutOfBoundsException If the named child does not exist. | |
64 | */ | |
65 | public function get($name); | |
66 | ||
67 | /** | |
68 | * Returns whether a child with the given name exists. | |
69 | * | |
70 | * @param string $name The name of the child | |
71 | * | |
72 | * @return Boolean | |
73 | */ | |
74 | public function has($name); | |
75 | ||
76 | /** | |
77 | * Removes a child from the form. | |
78 | * | |
79 | * @param string $name The name of the child to remove | |
80 | * | |
81 | * @return FormInterface The form instance | |
82 | * | |
83 | * @throws Exception\AlreadySubmittedException If the form has already been submitted. | |
84 | */ | |
85 | public function remove($name); | |
86 | ||
87 | /** | |
88 | * Returns all children in this group. | |
89 | * | |
90 | * @return FormInterface[] An array of FormInterface instances | |
91 | */ | |
92 | public function all(); | |
93 | ||
94 | /** | |
95 | * Returns all errors. | |
96 | * | |
97 | * @return FormError[] An array of FormError instances that occurred during validation | |
98 | */ | |
99 | public function getErrors(); | |
100 | ||
101 | /** | |
102 | * Updates the form with default data. | |
103 | * | |
104 | * @param mixed $modelData The data formatted as expected for the underlying object | |
105 | * | |
106 | * @return FormInterface The form instance | |
107 | * | |
108 | * @throws Exception\AlreadySubmittedException If the form has already been submitted. | |
109 | * @throws Exception\LogicException If listeners try to call setData in a cycle. Or if | |
110 | * the view data does not match the expected type | |
111 | * according to {@link FormConfigInterface::getDataClass}. | |
112 | */ | |
113 | public function setData($modelData); | |
114 | ||
115 | /** | |
116 | * Returns the data in the format needed for the underlying object. | |
117 | * | |
118 | * @return mixed | |
119 | */ | |
120 | public function getData(); | |
121 | ||
122 | /** | |
123 | * Returns the normalized data of the field. | |
124 | * | |
125 | * @return mixed When the field is not submitted, the default data is returned. | |
126 | * When the field is submitted, the normalized submitted data is | |
127 | * returned if the field is valid, null otherwise. | |
128 | */ | |
129 | public function getNormData(); | |
130 | ||
131 | /** | |
132 | * Returns the data transformed by the value transformer. | |
133 | * | |
134 | * @return mixed | |
135 | */ | |
136 | public function getViewData(); | |
137 | ||
138 | /** | |
139 | * Returns the extra data. | |
140 | * | |
141 | * @return array The submitted data which do not belong to a child | |
142 | */ | |
143 | public function getExtraData(); | |
144 | ||
145 | /** | |
146 | * Returns the form's configuration. | |
147 | * | |
148 | * @return FormConfigInterface The configuration. | |
149 | */ | |
150 | public function getConfig(); | |
151 | ||
152 | /** | |
153 | * Returns whether the form is submitted. | |
154 | * | |
155 | * @return Boolean true if the form is submitted, false otherwise | |
156 | */ | |
157 | public function isSubmitted(); | |
158 | ||
159 | /** | |
160 | * Returns the name by which the form is identified in forms. | |
161 | * | |
162 | * @return string The name of the form. | |
163 | */ | |
164 | public function getName(); | |
165 | ||
166 | /** | |
167 | * Returns the property path that the form is mapped to. | |
168 | * | |
169 | * @return \Symfony\Component\PropertyAccess\PropertyPathInterface The property path. | |
170 | */ | |
171 | public function getPropertyPath(); | |
172 | ||
173 | /** | |
174 | * Adds an error to this form. | |
175 | * | |
176 | * @param FormError $error | |
177 | * | |
178 | * @return FormInterface The form instance | |
179 | */ | |
180 | public function addError(FormError $error); | |
181 | ||
182 | /** | |
183 | * Returns whether the form and all children are valid. | |
184 | * | |
185 | * If the form is not submitted, this method always returns false. | |
186 | * | |
187 | * @return Boolean | |
188 | */ | |
189 | public function isValid(); | |
190 | ||
191 | /** | |
192 | * Returns whether the form is required to be filled out. | |
193 | * | |
194 | * If the form has a parent and the parent is not required, this method | |
195 | * will always return false. Otherwise the value set with setRequired() | |
196 | * is returned. | |
197 | * | |
198 | * @return Boolean | |
199 | */ | |
200 | public function isRequired(); | |
201 | ||
202 | /** | |
203 | * Returns whether this form is disabled. | |
204 | * | |
205 | * The content of a disabled form is displayed, but not allowed to be | |
206 | * modified. The validation of modified disabled forms should fail. | |
207 | * | |
208 | * Forms whose parents are disabled are considered disabled regardless of | |
209 | * their own state. | |
210 | * | |
211 | * @return Boolean | |
212 | */ | |
213 | public function isDisabled(); | |
214 | ||
215 | /** | |
216 | * Returns whether the form is empty. | |
217 | * | |
218 | * @return Boolean | |
219 | */ | |
220 | public function isEmpty(); | |
221 | ||
222 | /** | |
223 | * Returns whether the data in the different formats is synchronized. | |
224 | * | |
225 | * @return Boolean | |
226 | */ | |
227 | public function isSynchronized(); | |
228 | ||
229 | /** | |
230 | * Initializes the form tree. | |
231 | * | |
232 | * Should be called on the root form after constructing the tree. | |
233 | * | |
234 | * @return FormInterface The form instance. | |
235 | */ | |
236 | public function initialize(); | |
237 | ||
238 | /** | |
239 | * Inspects the given request and calls {@link submit()} if the form was | |
240 | * submitted. | |
241 | * | |
242 | * Internally, the request is forwarded to the configured | |
243 | * {@link RequestHandlerInterface} instance, which determines whether to | |
244 | * submit the form or not. | |
245 | * | |
246 | * @param mixed $request The request to handle. | |
247 | * | |
248 | * @return FormInterface The form instance. | |
249 | */ | |
250 | public function handleRequest($request = null); | |
251 | ||
252 | /** | |
253 | * Submits data to the form, transforms and validates it. | |
254 | * | |
255 | * @param null|string|array $submittedData The submitted data. | |
256 | * @param Boolean $clearMissing Whether to set fields to NULL | |
257 | * when they are missing in the | |
258 | * submitted data. | |
259 | * | |
260 | * @return FormInterface The form instance | |
261 | * | |
262 | * @throws Exception\AlreadySubmittedException If the form has already been submitted. | |
263 | */ | |
264 | public function submit($submittedData, $clearMissing = true); | |
265 | ||
266 | /** | |
267 | * Returns the root of the form tree. | |
268 | * | |
269 | * @return FormInterface The root of the tree | |
270 | */ | |
271 | public function getRoot(); | |
272 | ||
273 | /** | |
274 | * Returns whether the field is the root of the form tree. | |
275 | * | |
276 | * @return Boolean | |
277 | */ | |
278 | public function isRoot(); | |
279 | ||
280 | /** | |
281 | * Creates a view. | |
282 | * | |
283 | * @param FormView $parent The parent view | |
284 | * | |
285 | * @return FormView The view | |
286 | */ | |
287 | public function createView(FormView $parent = null); | |
288 | } |