290 lines
9.3 KiB
PHP
290 lines
9.3 KiB
PHP
|
<?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>
|
||
|
|
*
|
||
|
|
* @extends \ArrayAccess<string, FormInterface>
|
||
|
|
* @extends \Traversable<string, FormInterface>
|
||
|
|
*/
|
||
|
|
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): static;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns the parent form.
|
||
|
|
*/
|
||
|
|
public function getParent(): ?self;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* 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(self|string $child, ?string $type = null, array $options = []): static;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns the child with the given name.
|
||
|
|
*
|
||
|
|
* @throws Exception\OutOfBoundsException if the named child does not exist
|
||
|
|
*/
|
||
|
|
public function get(string $name): self;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns whether a child with the given name exists.
|
||
|
|
*/
|
||
|
|
public function has(string $name): bool;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Removes a child from the form.
|
||
|
|
*
|
||
|
|
* @return $this
|
||
|
|
*
|
||
|
|
* @throws Exception\AlreadySubmittedException if the form has already been submitted
|
||
|
|
*/
|
||
|
|
public function remove(string $name): static;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns all children in this group.
|
||
|
|
*
|
||
|
|
* @return self[]
|
||
|
|
*/
|
||
|
|
public function all(): array;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* 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
|
||
|
|
*/
|
||
|
|
public function getErrors(bool $deep = false, bool $flatten = true): FormErrorIterator;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* 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(mixed $modelData): static;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* 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(): mixed;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* 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(): mixed;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* 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.
|
||
|
|
*
|
||
|
|
* @throws Exception\RuntimeException If the form inherits data but has no parent
|
||
|
|
*/
|
||
|
|
public function getViewData(): mixed;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns the extra submitted data.
|
||
|
|
*
|
||
|
|
* @return array The submitted data which do not belong to a child
|
||
|
|
*/
|
||
|
|
public function getExtraData(): array;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns the form's configuration.
|
||
|
|
*/
|
||
|
|
public function getConfig(): FormConfigInterface;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns whether the form is submitted.
|
||
|
|
*/
|
||
|
|
public function isSubmitted(): bool;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns the name by which the form is identified in forms.
|
||
|
|
*
|
||
|
|
* Only root forms are allowed to have an empty name.
|
||
|
|
*/
|
||
|
|
public function getName(): string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns the property path that the form is mapped to.
|
||
|
|
*/
|
||
|
|
public function getPropertyPath(): ?PropertyPathInterface;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Adds an error to this form.
|
||
|
|
*
|
||
|
|
* @return $this
|
||
|
|
*/
|
||
|
|
public function addError(FormError $error): static;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns whether the form and all children are valid.
|
||
|
|
*
|
||
|
|
* @throws Exception\LogicException if the form is not submitted
|
||
|
|
*/
|
||
|
|
public function isValid(): bool;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* 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.
|
||
|
|
*/
|
||
|
|
public function isRequired(): bool;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* 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.
|
||
|
|
*/
|
||
|
|
public function isDisabled(): bool;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns whether the form is empty.
|
||
|
|
*/
|
||
|
|
public function isEmpty(): bool;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* 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.
|
||
|
|
*/
|
||
|
|
public function isSynchronized(): bool;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns the data transformation failure, if any, during submission.
|
||
|
|
*/
|
||
|
|
public function getTransformationFailure(): ?Exception\TransformationFailedException;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* 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(): static;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* 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.
|
||
|
|
*
|
||
|
|
* @return $this
|
||
|
|
*/
|
||
|
|
public function handleRequest(mixed $request = null): static;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* 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(string|array|null $submittedData, bool $clearMissing = true): static;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns the root of the form tree.
|
||
|
|
*/
|
||
|
|
public function getRoot(): self;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns whether the field is the root of the form tree.
|
||
|
|
*/
|
||
|
|
public function isRoot(): bool;
|
||
|
|
|
||
|
|
public function createView(?FormView $parent = null): FormView;
|
||
|
|
}
|