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\PropertyAccess\PropertyPathInterface;
  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.      * @param FormInterface|null $parent The parent form or null if it's the root
  27.      *
  28.      * @return $this
  29.      *
  30.      * @throws Exception\AlreadySubmittedException if the form has already been submitted
  31.      * @throws Exception\LogicException            when trying to set a parent for a form with
  32.      *                                             an empty name
  33.      */
  34.     public function setParent(self $parent = null);
  36.     /**
  37.      * Returns the parent form.
  38.      *
  39.      * @return self|null The parent form or null if there is none
  40.      */
  41.     public function getParent();
  43.     /**
  44.      * Adds or replaces a child to the form.
  45.      *
  46.      * @param FormInterface|string $child   The FormInterface instance or the name of the child
  47.      * @param string|null          $type    The child's type, if a name was passed
  48.      * @param array                $options The child's options, if a name was passed
  49.      *
  50.      * @return $this
  51.      *
  52.      * @throws Exception\AlreadySubmittedException if the form has already been submitted
  53.      * @throws Exception\LogicException            when trying to add a child to a non-compound form
  54.      * @throws Exception\UnexpectedTypeException   if $child or $type has an unexpected type
  55.      */
  56.     public function add($child, $type = null, array $options = []);
  58.     /**
  59.      * Returns the child with the given name.
  60.      *
  61.      * @param string $name The name of the child
  62.      *
  63.      * @return self
  64.      *
  65.      * @throws Exception\OutOfBoundsException if the named child does not exist
  66.      */
  67.     public function get($name);
  69.     /**
  70.      * Returns whether a child with the given name exists.
  71.      *
  72.      * @param string $name The name of the child
  73.      *
  74.      * @return bool
  75.      */
  76.     public function has($name);
  78.     /**
  79.      * Removes a child from the form.
  80.      *
  81.      * @param string $name The name of the child to remove
  82.      *
  83.      * @return $this
  84.      *
  85.      * @throws Exception\AlreadySubmittedException if the form has already been submitted
  86.      */
  87.     public function remove($name);
  89.     /**
  90.      * Returns all children in this group.
  91.      *
  92.      * @return self[]
  93.      */
  94.     public function all();
  96.     /**
  97.      * Returns the errors of this form.
  98.      *
  99.      * @param bool $deep    Whether to include errors of child forms as well
  100.      * @param bool $flatten Whether to flatten the list of errors in case
  101.      *                      $deep is set to true
  102.      *
  103.      * @return FormErrorIterator An iterator over the {@link FormError}
  104.      *                           instances that where added to this form
  105.      */
  106.     public function getErrors($deep = false, $flatten = true);
  108.     /**
  109.      * Updates the form with default model data.
  110.      *
  111.      * @param mixed $modelData The data formatted as expected for the underlying object
  112.      *
  113.      * @return $this
  114.      *
  115.      * @throws Exception\AlreadySubmittedException     If the form has already been submitted
  116.      * @throws Exception\LogicException                if the view data does not match the expected type
  117.      *                                                 according to {@link FormConfigInterface::getDataClass}
  118.      * @throws Exception\RuntimeException              If listeners try to call setData in a cycle or if
  119.      *                                                 the form inherits data from its parent
  120.      * @throws Exception\TransformationFailedException if the synchronization failed
  121.      */
  122.     public function setData($modelData);
  124.     /**
  125.      * Returns the model data in the format needed for the underlying object.
  126.      *
  127.      * @return mixed When the field is not submitted, the default data is returned.
  128.      *               When the field is submitted, the default data has been bound
  129.      *               to the submitted view data.
  130.      *
  131.      * @throws Exception\RuntimeException If the form inherits data but has no parent
  132.      */
  133.     public function getData();
  135.     /**
  136.      * Returns the normalized data of the field, used as internal bridge
  137.      * between model data and view data.
  138.      *
  139.      * @return mixed When the field is not submitted, the default data is returned.
  140.      *               When the field is submitted, the normalized submitted data
  141.      *               is returned if the field is synchronized with the view data,
  142.      *               null otherwise.
  143.      *
  144.      * @throws Exception\RuntimeException If the form inherits data but has no parent
  145.      */
  146.     public function getNormData();
  148.     /**
  149.      * Returns the view data of the field.
  150.      *
  151.      * It may be defined by {@link FormConfigInterface::getDataClass}.
  152.      *
  153.      * There are two cases:
  154.      *
  155.      * - When the form is compound the view data is mapped to the children.
  156.      *   Each child will use its mapped data as model data.
  157.      *   It can be an array, an object or null.
  158.      *
  159.      * - When the form is simple its view data is used to be bound
  160.      *   to the submitted data.
  161.      *   It can be a string or an array.
  162.      *
  163.      * In both cases the view data is the actual altered data on submission.
  164.      *
  165.      * @return mixed
  166.      *
  167.      * @throws Exception\RuntimeException If the form inherits data but has no parent
  168.      */
  169.     public function getViewData();
  171.     /**
  172.      * Returns the extra submitted data.
  173.      *
  174.      * @return array The submitted data which do not belong to a child
  175.      */
  176.     public function getExtraData();
  178.     /**
  179.      * Returns the form's configuration.
  180.      *
  181.      * @return FormConfigInterface The configuration instance
  182.      */
  183.     public function getConfig();
  185.     /**
  186.      * Returns whether the form is submitted.
  187.      *
  188.      * @return bool true if the form is submitted, false otherwise
  189.      */
  190.     public function isSubmitted();
  192.     /**
  193.      * Returns the name by which the form is identified in forms.
  194.      *
  195.      * Only root forms are allowed to have an empty name.
  196.      *
  197.      * @return string The name of the form
  198.      */
  199.     public function getName();
  201.     /**
  202.      * Returns the property path that the form is mapped to.
  203.      *
  204.      * @return PropertyPathInterface|null The property path instance
  205.      */
  206.     public function getPropertyPath();
  208.     /**
  209.      * Adds an error to this form.
  210.      *
  211.      * @return $this
  212.      */
  213.     public function addError(FormError $error);
  215.     /**
  216.      * Returns whether the form and all children are valid.
  217.      *
  218.      * If the form is not submitted, this method always returns false (but will throw an exception in 4.0).
  219.      *
  220.      * @return bool
  221.      */
  222.     public function isValid();
  224.     /**
  225.      * Returns whether the form is required to be filled out.
  226.      *
  227.      * If the form has a parent and the parent is not required, this method
  228.      * will always return false. Otherwise the value set with setRequired()
  229.      * is returned.
  230.      *
  231.      * @return bool
  232.      */
  233.     public function isRequired();
  235.     /**
  236.      * Returns whether this form is disabled.
  237.      *
  238.      * The content of a disabled form is displayed, but not allowed to be
  239.      * modified. The validation of modified disabled forms should fail.
  240.      *
  241.      * Forms whose parents are disabled are considered disabled regardless of
  242.      * their own state.
  243.      *
  244.      * @return bool
  245.      */
  246.     public function isDisabled();
  248.     /**
  249.      * Returns whether the form is empty.
  250.      *
  251.      * @return bool
  252.      */
  253.     public function isEmpty();
  255.     /**
  256.      * Returns whether the data in the different formats is synchronized.
  257.      *
  258.      * If the data is not synchronized, you can get the transformation failure
  259.      * by calling {@link getTransformationFailure()}.
  260.      *
  261.      * If the form is not submitted, this method always returns true.
  262.      *
  263.      * @return bool
  264.      */
  265.     public function isSynchronized();
  267.     /**
  268.      * Returns the data transformation failure, if any, during submission.
  269.      *
  270.      * @return Exception\TransformationFailedException|null The transformation failure or null
  271.      */
  272.     public function getTransformationFailure();
  274.     /**
  275.      * Initializes the form tree.
  276.      *
  277.      * Should be called on the root form after constructing the tree.
  278.      *
  279.      * @return $this
  280.      *
  281.      * @throws Exception\RuntimeException If the form is not the root
  282.      */
  283.     public function initialize();
  285.     /**
  286.      * Inspects the given request and calls {@link submit()} if the form was
  287.      * submitted.
  288.      *
  289.      * Internally, the request is forwarded to the configured
  290.      * {@link RequestHandlerInterface} instance, which determines whether to
  291.      * submit the form or not.
  292.      *
  293.      * @param mixed $request The request to handle
  294.      *
  295.      * @return $this
  296.      */
  297.     public function handleRequest($request = null);
  299.     /**
  300.      * Submits data to the form.
  301.      *
  302.      * @param string|array|null $submittedData The submitted data
  303.      * @param bool              $clearMissing  Whether to set fields to NULL
  304.      *                                         when they are missing in the
  305.      *                                         submitted data. This argument
  306.      *                                         is only used in compound form
  307.      *
  308.      * @return $this
  309.      *
  310.      * @throws Exception\AlreadySubmittedException if the form has already been submitted
  311.      */
  312.     public function submit($submittedData, $clearMissing = true);
  314.     /**
  315.      * Returns the root of the form tree.
  316.      *
  317.      * @return self The root of the tree, may be the instance itself
  318.      */
  319.     public function getRoot();
  321.     /**
  322.      * Returns whether the field is the root of the form tree.
  323.      *
  324.      * @return bool
  325.      */
  326.     public function isRoot();
  328.     /**
  329.      * @return FormView The view
  330.      */
  331.     public function createView(FormView $parent = null);
  332. }