vendor/symfony/form/Symfony/Component/Form/FormInterface.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\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 }