vendor/symfony/form/FormInterface.php line 57

  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.  * @extends \ArrayAccess<string, FormInterface>
  22.  * @extends \Traversable<string, FormInterface>
  23.  */
  24. interface FormInterface extends \ArrayAccess, \Traversable, \Countable
  25. {
  26.     /**
  27.      * Sets the parent form.
  28.      *
  29.      * @param FormInterface|null $parent The parent form or null if it's the root
  30.      *
  31.      * @return $this
  32.      *
  33.      * @throws Exception\AlreadySubmittedException if the form has already been submitted
  34.      * @throws Exception\LogicException            when trying to set a parent for a form with
  35.      *                                             an empty name
  36.      */
  37.     public function setParent(?self $parent): static;
  39.     /**
  40.      * Returns the parent form.
  41.      */
  42.     public function getParent(): ?self;
  44.     /**
  45.      * Adds or replaces a child to the form.
  46.      *
  47.      * @param FormInterface|string $child   The FormInterface instance or the name of the child
  48.      * @param string|null          $type    The child's type, if a name was passed
  49.      * @param array                $options The child's options, if a name was passed
  50.      *
  51.      * @return $this
  52.      *
  53.      * @throws Exception\AlreadySubmittedException if the form has already been submitted
  54.      * @throws Exception\LogicException            when trying to add a child to a non-compound form
  55.      * @throws Exception\UnexpectedTypeException   if $child or $type has an unexpected type
  56.      */
  57.     public function add(self|string $child, string $type = null, array $options = []): static;
  59.     /**
  60.      * Returns the child with the given name.
  61.      *
  62.      * @throws Exception\OutOfBoundsException if the named child does not exist
  63.      */
  64.     public function get(string $name): self;
  66.     /**
  67.      * Returns whether a child with the given name exists.
  68.      */
  69.     public function has(string $name): bool;
  71.     /**
  72.      * Removes a child from the form.
  73.      *
  74.      * @return $this
  75.      *
  76.      * @throws Exception\AlreadySubmittedException if the form has already been submitted
  77.      */
  78.     public function remove(string $name): static;
  80.     /**
  81.      * Returns all children in this group.
  82.      *
  83.      * @return self[]
  84.      */
  85.     public function all(): array;
  87.     /**
  88.      * Returns the errors of this form.
  89.      *
  90.      * @param bool $deep    Whether to include errors of child forms as well
  91.      * @param bool $flatten Whether to flatten the list of errors in case
  92.      *                      $deep is set to true
  93.      */
  94.     public function getErrors(bool $deep = false, bool $flatten = true): FormErrorIterator;
  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(mixed $modelData): static;
  112.     /**
  113.      * Returns the model data in the format needed for the underlying object.
  114.      *
  115.      * @return mixed When the field is not submitted, the default data is returned.
  116.      *               When the field is submitted, the default data has been bound
  117.      *               to the submitted view data.
  118.      *
  119.      * @throws Exception\RuntimeException If the form inherits data but has no parent
  120.      */
  121.     public function getData(): mixed;
  123.     /**
  124.      * Returns the normalized data of the field, used as internal bridge
  125.      * between model data and view data.
  126.      *
  127.      * @return mixed When the field is not submitted, the default data is returned.
  128.      *               When the field is submitted, the normalized submitted data
  129.      *               is returned if the field is synchronized with the view data,
  130.      *               null otherwise.
  131.      *
  132.      * @throws Exception\RuntimeException If the form inherits data but has no parent
  133.      */
  134.     public function getNormData(): mixed;
  136.     /**
  137.      * Returns the view data of the field.
  138.      *
  139.      * It may be defined by {@link FormConfigInterface::getDataClass}.
  140.      *
  141.      * There are two cases:
  142.      *
  143.      * - When the form is compound the view data is mapped to the children.
  144.      *   Each child will use its mapped data as model data.
  145.      *   It can be an array, an object or null.
  146.      *
  147.      * - When the form is simple its view data is used to be bound
  148.      *   to the submitted data.
  149.      *   It can be a string or an array.
  150.      *
  151.      * In both cases the view data is the actual altered data on submission.
  152.      *
  153.      * @throws Exception\RuntimeException If the form inherits data but has no parent
  154.      */
  155.     public function getViewData(): mixed;
  157.     /**
  158.      * Returns the extra submitted data.
  159.      *
  160.      * @return array The submitted data which do not belong to a child
  161.      */
  162.     public function getExtraData(): array;
  164.     /**
  165.      * Returns the form's configuration.
  166.      */
  167.     public function getConfig(): FormConfigInterface;
  169.     /**
  170.      * Returns whether the form is submitted.
  171.      */
  172.     public function isSubmitted(): bool;
  174.     /**
  175.      * Returns the name by which the form is identified in forms.
  176.      *
  177.      * Only root forms are allowed to have an empty name.
  178.      */
  179.     public function getName(): string;
  181.     /**
  182.      * Returns the property path that the form is mapped to.
  183.      */
  184.     public function getPropertyPath(): ?PropertyPathInterface;
  186.     /**
  187.      * Adds an error to this form.
  188.      *
  189.      * @return $this
  190.      */
  191.     public function addError(FormError $error): static;
  193.     /**
  194.      * Returns whether the form and all children are valid.
  195.      *
  196.      * @throws Exception\LogicException if the form is not submitted
  197.      */
  198.     public function isValid(): bool;
  200.     /**
  201.      * Returns whether the form is required to be filled out.
  202.      *
  203.      * If the form has a parent and the parent is not required, this method
  204.      * will always return false. Otherwise the value set with setRequired()
  205.      * is returned.
  206.      */
  207.     public function isRequired(): bool;
  209.     /**
  210.      * Returns whether this form is disabled.
  211.      *
  212.      * The content of a disabled form is displayed, but not allowed to be
  213.      * modified. The validation of modified disabled forms should fail.
  214.      *
  215.      * Forms whose parents are disabled are considered disabled regardless of
  216.      * their own state.
  217.      */
  218.     public function isDisabled(): bool;
  220.     /**
  221.      * Returns whether the form is empty.
  222.      */
  223.     public function isEmpty(): bool;
  225.     /**
  226.      * Returns whether the data in the different formats is synchronized.
  227.      *
  228.      * If the data is not synchronized, you can get the transformation failure
  229.      * by calling {@link getTransformationFailure()}.
  230.      *
  231.      * If the form is not submitted, this method always returns true.
  232.      */
  233.     public function isSynchronized(): bool;
  235.     /**
  236.      * Returns the data transformation failure, if any, during submission.
  237.      */
  238.     public function getTransformationFailure(): ?Exception\TransformationFailedException;
  240.     /**
  241.      * Initializes the form tree.
  242.      *
  243.      * Should be called on the root form after constructing the tree.
  244.      *
  245.      * @return $this
  246.      *
  247.      * @throws Exception\RuntimeException If the form is not the root
  248.      */
  249.     public function initialize(): static;
  251.     /**
  252.      * Inspects the given request and calls {@link submit()} if the form was
  253.      * submitted.
  254.      *
  255.      * Internally, the request is forwarded to the configured
  256.      * {@link RequestHandlerInterface} instance, which determines whether to
  257.      * submit the form or not.
  258.      *
  259.      * @return $this
  260.      */
  261.     public function handleRequest(mixed $request = null): static;
  263.     /**
  264.      * Submits data to the form.
  265.      *
  266.      * @param string|array|null $submittedData The submitted data
  267.      * @param bool              $clearMissing  Whether to set fields to NULL
  268.      *                                         when they are missing in the
  269.      *                                         submitted data. This argument
  270.      *                                         is only used in compound form
  271.      *
  272.      * @return $this
  273.      *
  274.      * @throws Exception\AlreadySubmittedException if the form has already been submitted
  275.      */
  276.     public function submit(string|array|null $submittedData, bool $clearMissing = true): static;
  278.     /**
  279.      * Returns the root of the form tree.
  280.      */
  281.     public function getRoot(): self;
  283.     /**
  284.      * Returns whether the field is the root of the form tree.
  285.      */
  286.     public function isRoot(): bool;
  288.     public function createView(FormView $parent = null): FormView;
  289. }