123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326 |
- <?php
- /*
- * This file is part of the Symfony package.
- *
- * (c) Fabien Potencier <fabien@symfony.com>
- *
- * For the full copyright and license information, please view the LICENSE
- * file that was distributed with this source code.
- */
- namespace Symfony\Component\Form;
- use Symfony\Component\PropertyAccess\PropertyPathInterface;
- /**
- * A form group bundling multiple forms in a hierarchical structure.
- *
- * @author Bernhard Schussek <bschussek@gmail.com>
- */
- interface FormInterface extends \ArrayAccess, \Traversable, \Countable
- {
- /**
- * Sets the parent form.
- *
- * @param FormInterface|null $parent The parent form or null if it's the root
- *
- * @return $this
- *
- * @throws Exception\AlreadySubmittedException if the form has already been submitted
- * @throws Exception\LogicException when trying to set a parent for a form with
- * an empty name
- */
- public function setParent(self $parent = null);
- /**
- * Returns the parent form.
- *
- * @return self|null The parent form or null if there is none
- */
- public function getParent();
- /**
- * Adds or replaces a child to the form.
- *
- * @param FormInterface|string $child The FormInterface instance or the name of the child
- * @param string|null $type The child's type, if a name was passed
- * @param array $options The child's options, if a name was passed
- *
- * @return $this
- *
- * @throws Exception\AlreadySubmittedException if the form has already been submitted
- * @throws Exception\LogicException when trying to add a child to a non-compound form
- * @throws Exception\UnexpectedTypeException if $child or $type has an unexpected type
- */
- public function add($child, string $type = null, array $options = []);
- /**
- * Returns the child with the given name.
- *
- * @return self
- *
- * @throws Exception\OutOfBoundsException if the named child does not exist
- */
- public function get(string $name);
- /**
- * Returns whether a child with the given name exists.
- *
- * @return bool
- */
- public function has(string $name);
- /**
- * Removes a child from the form.
- *
- * @return $this
- *
- * @throws Exception\AlreadySubmittedException if the form has already been submitted
- */
- public function remove(string $name);
- /**
- * Returns all children in this group.
- *
- * @return self[]
- */
- public function all();
- /**
- * Returns the errors of this form.
- *
- * @param bool $deep Whether to include errors of child forms as well
- * @param bool $flatten Whether to flatten the list of errors in case
- * $deep is set to true
- *
- * @return FormErrorIterator An iterator over the {@link FormError}
- * instances that where added to this form
- */
- public function getErrors(bool $deep = false, bool $flatten = true);
- /**
- * Updates the form with default model data.
- *
- * @param mixed $modelData The data formatted as expected for the underlying object
- *
- * @return $this
- *
- * @throws Exception\AlreadySubmittedException If the form has already been submitted
- * @throws Exception\LogicException if the view data does not match the expected type
- * according to {@link FormConfigInterface::getDataClass}
- * @throws Exception\RuntimeException If listeners try to call setData in a cycle or if
- * the form inherits data from its parent
- * @throws Exception\TransformationFailedException if the synchronization failed
- */
- public function setData($modelData);
- /**
- * Returns the model data in the format needed for the underlying object.
- *
- * @return mixed When the field is not submitted, the default data is returned.
- * When the field is submitted, the default data has been bound
- * to the submitted view data.
- *
- * @throws Exception\RuntimeException If the form inherits data but has no parent
- */
- public function getData();
- /**
- * Returns the normalized data of the field, used as internal bridge
- * between model data and view data.
- *
- * @return mixed When the field is not submitted, the default data is returned.
- * When the field is submitted, the normalized submitted data
- * is returned if the field is synchronized with the view data,
- * null otherwise.
- *
- * @throws Exception\RuntimeException If the form inherits data but has no parent
- */
- public function getNormData();
- /**
- * Returns the view data of the field.
- *
- * It may be defined by {@link FormConfigInterface::getDataClass}.
- *
- * There are two cases:
- *
- * - When the form is compound the view data is mapped to the children.
- * Each child will use its mapped data as model data.
- * It can be an array, an object or null.
- *
- * - When the form is simple its view data is used to be bound
- * to the submitted data.
- * It can be a string or an array.
- *
- * In both cases the view data is the actual altered data on submission.
- *
- * @return mixed
- *
- * @throws Exception\RuntimeException If the form inherits data but has no parent
- */
- public function getViewData();
- /**
- * Returns the extra submitted data.
- *
- * @return array The submitted data which do not belong to a child
- */
- public function getExtraData();
- /**
- * Returns the form's configuration.
- *
- * @return FormConfigInterface The configuration instance
- */
- public function getConfig();
- /**
- * Returns whether the form is submitted.
- *
- * @return bool true if the form is submitted, false otherwise
- */
- public function isSubmitted();
- /**
- * Returns the name by which the form is identified in forms.
- *
- * Only root forms are allowed to have an empty name.
- *
- * @return string The name of the form
- */
- public function getName();
- /**
- * Returns the property path that the form is mapped to.
- *
- * @return PropertyPathInterface|null The property path instance
- */
- public function getPropertyPath();
- /**
- * Adds an error to this form.
- *
- * @return $this
- */
- public function addError(FormError $error);
- /**
- * Returns whether the form and all children are valid.
- *
- * @throws Exception\LogicException if the form is not submitted
- *
- * @return bool
- */
- public function isValid();
- /**
- * Returns whether the form is required to be filled out.
- *
- * If the form has a parent and the parent is not required, this method
- * will always return false. Otherwise the value set with setRequired()
- * is returned.
- *
- * @return bool
- */
- public function isRequired();
- /**
- * Returns whether this form is disabled.
- *
- * The content of a disabled form is displayed, but not allowed to be
- * modified. The validation of modified disabled forms should fail.
- *
- * Forms whose parents are disabled are considered disabled regardless of
- * their own state.
- *
- * @return bool
- */
- public function isDisabled();
- /**
- * Returns whether the form is empty.
- *
- * @return bool
- */
- public function isEmpty();
- /**
- * Returns whether the data in the different formats is synchronized.
- *
- * If the data is not synchronized, you can get the transformation failure
- * by calling {@link getTransformationFailure()}.
- *
- * If the form is not submitted, this method always returns true.
- *
- * @return bool
- */
- public function isSynchronized();
- /**
- * Returns the data transformation failure, if any, during submission.
- *
- * @return Exception\TransformationFailedException|null The transformation failure or null
- */
- public function getTransformationFailure();
- /**
- * Initializes the form tree.
- *
- * Should be called on the root form after constructing the tree.
- *
- * @return $this
- *
- * @throws Exception\RuntimeException If the form is not the root
- */
- public function initialize();
- /**
- * Inspects the given request and calls {@link submit()} if the form was
- * submitted.
- *
- * Internally, the request is forwarded to the configured
- * {@link RequestHandlerInterface} instance, which determines whether to
- * submit the form or not.
- *
- * @param mixed $request The request to handle
- *
- * @return $this
- */
- public function handleRequest($request = null);
- /**
- * Submits data to the form.
- *
- * @param string|array|null $submittedData The submitted data
- * @param bool $clearMissing Whether to set fields to NULL
- * when they are missing in the
- * submitted data. This argument
- * is only used in compound form
- *
- * @return $this
- *
- * @throws Exception\AlreadySubmittedException if the form has already been submitted
- */
- public function submit($submittedData, bool $clearMissing = true);
- /**
- * Returns the root of the form tree.
- *
- * @return self The root of the tree, may be the instance itself
- */
- public function getRoot();
- /**
- * Returns whether the field is the root of the form tree.
- *
- * @return bool
- */
- public function isRoot();
- /**
- * @return FormView The view
- */
- public function createView(FormView $parent = null);
- }
|