vendor/symfony/form/FormInterface.php line 21

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