vendor/symfony/symfony/src/Symfony/Component/Form/FormInterface.php line 21

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