2010-06-24 09:40:05 +01:00
|
|
|
<?php
|
|
|
|
|
2010-10-02 11:38:11 +01:00
|
|
|
/*
|
2011-01-15 13:29:43 +00:00
|
|
|
* This file is part of the Symfony package.
|
2010-10-02 11:38:11 +01:00
|
|
|
*
|
2011-03-06 11:40:06 +00:00
|
|
|
* (c) Fabien Potencier <fabien@symfony.com>
|
2010-10-02 11:38:11 +01:00
|
|
|
*
|
2011-01-15 13:29:43 +00:00
|
|
|
* For the full copyright and license information, please view the LICENSE
|
|
|
|
* file that was distributed with this source code.
|
2010-10-02 11:38:11 +01:00
|
|
|
*/
|
|
|
|
|
2011-01-15 13:29:43 +00:00
|
|
|
namespace Symfony\Component\Form;
|
|
|
|
|
2014-09-26 12:06:33 +01:00
|
|
|
use Symfony\Component\Form\Exception\TransformationFailedException;
|
|
|
|
|
2010-06-24 09:40:05 +01:00
|
|
|
/**
|
2012-08-26 07:28:19 +01:00
|
|
|
* A form group bundling multiple forms in a hierarchical structure.
|
2010-06-24 09:40:05 +01:00
|
|
|
*
|
2012-05-26 08:48:33 +01:00
|
|
|
* @author Bernhard Schussek <bschussek@gmail.com>
|
2010-06-24 09:40:05 +01:00
|
|
|
*/
|
2011-03-20 12:35:19 +00:00
|
|
|
interface FormInterface extends \ArrayAccess, \Traversable, \Countable
|
2010-06-24 09:40:05 +01:00
|
|
|
{
|
2011-03-20 12:35:19 +00:00
|
|
|
/**
|
|
|
|
* Sets the parent form.
|
|
|
|
*
|
2016-06-28 06:50:50 +01:00
|
|
|
* @param FormInterface|null $parent The parent form or null if it's the root
|
2012-05-20 10:18:31 +01:00
|
|
|
*
|
2016-12-26 07:50:27 +00:00
|
|
|
* @return self
|
2012-08-26 07:28:19 +01:00
|
|
|
*
|
2013-04-20 16:32:55 +01:00
|
|
|
* @throws Exception\AlreadySubmittedException If the form has already been submitted.
|
2014-11-30 13:33:44 +00:00
|
|
|
* @throws Exception\LogicException When trying to set a parent for a form with
|
|
|
|
* an empty name.
|
2011-03-20 12:35:19 +00:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function setParent(FormInterface $parent = null);
|
2011-03-20 12:35:19 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns the parent form.
|
|
|
|
*
|
2016-12-26 07:50:27 +00:00
|
|
|
* @return self|null The parent form or null if there is none
|
2011-03-20 12:35:19 +00:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function getParent();
|
2011-03-20 12:35:19 +00:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
2014-01-24 23:53:20 +00:00
|
|
|
* Adds or replaces a child to the form.
|
2011-05-10 14:32:14 +01:00
|
|
|
*
|
2016-06-28 06:50:50 +01:00
|
|
|
* @param FormInterface|string|int $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
|
2012-05-20 10:18:31 +01:00
|
|
|
*
|
2016-12-26 07:50:27 +00:00
|
|
|
* @return self
|
2012-08-26 07:28:19 +01:00
|
|
|
*
|
2014-11-30 13:33:44 +00:00
|
|
|
* @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.
|
2011-05-10 14:32:14 +01:00
|
|
|
*/
|
2012-12-14 15:05:05 +00:00
|
|
|
public function add($child, $type = null, array $options = array());
|
2011-04-15 10:06:51 +01:00
|
|
|
|
2012-01-18 06:05:44 +00:00
|
|
|
/**
|
|
|
|
* Returns the child with the given name.
|
2012-01-26 15:54:42 +00:00
|
|
|
*
|
2012-01-18 06:05:44 +00:00
|
|
|
* @param string $name The name of the child
|
2012-01-26 15:54:42 +00:00
|
|
|
*
|
2016-12-26 07:50:27 +00:00
|
|
|
* @return self
|
2012-08-26 07:28:19 +01:00
|
|
|
*
|
2012-08-26 08:47:56 +01:00
|
|
|
* @throws \OutOfBoundsException If the named child does not exist.
|
2012-01-18 06:05:44 +00:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function get($name);
|
2012-01-18 06:05:44 +00:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
|
|
|
* Returns whether a child with the given name exists.
|
|
|
|
*
|
2012-01-18 06:05:44 +00:00
|
|
|
* @param string $name The name of the child
|
2011-05-10 14:32:14 +01:00
|
|
|
*
|
2014-04-16 11:30:19 +01:00
|
|
|
* @return bool
|
2011-05-10 14:32:14 +01:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function has($name);
|
2011-04-15 10:06:51 +01:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
|
|
|
* Removes a child from the form.
|
|
|
|
*
|
2014-11-30 13:33:44 +00:00
|
|
|
* @param string $name The name of the child to remove
|
2012-05-20 10:18:31 +01:00
|
|
|
*
|
2016-12-26 07:50:27 +00:00
|
|
|
* @return $this
|
2012-08-26 07:28:19 +01:00
|
|
|
*
|
2013-04-20 16:32:55 +01:00
|
|
|
* @throws Exception\AlreadySubmittedException If the form has already been submitted.
|
2011-05-10 14:32:14 +01:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function remove($name);
|
2011-04-15 10:06:51 +01:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
|
|
|
* Returns all children in this group.
|
|
|
|
*
|
2016-12-26 07:50:27 +00:00
|
|
|
* @return self[]
|
2011-05-10 14:32:14 +01:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function all();
|
2011-03-22 00:40:02 +00:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
2013-12-31 16:24:28 +00:00
|
|
|
* Returns the errors of this form.
|
2011-05-10 14:32:14 +01:00
|
|
|
*
|
2014-12-04 20:26:11 +00:00
|
|
|
* @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
|
2013-12-31 16:24:28 +00:00
|
|
|
*
|
|
|
|
* @return FormErrorIterator An iterator over the {@link FormError}
|
|
|
|
* instances that where added to this form
|
2011-05-10 14:32:14 +01:00
|
|
|
*/
|
2014-01-10 12:53:52 +00:00
|
|
|
public function getErrors($deep = false, $flatten = true);
|
2011-03-22 22:20:14 +00:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
2012-08-26 07:28:19 +01:00
|
|
|
* Updates the form with default data.
|
2011-05-10 14:32:14 +01:00
|
|
|
*
|
2014-11-30 13:33:44 +00:00
|
|
|
* @param mixed $modelData The data formatted as expected for the underlying object
|
2011-05-10 14:32:14 +01:00
|
|
|
*
|
2016-12-26 07:50:27 +00:00
|
|
|
* @return $this
|
2012-08-26 07:28:19 +01:00
|
|
|
*
|
2013-04-20 16:32:55 +01:00
|
|
|
* @throws Exception\AlreadySubmittedException If the form has already been submitted.
|
2014-11-30 13:33:44 +00:00
|
|
|
* @throws Exception\LogicException If listeners try to call setData in a cycle. Or if
|
|
|
|
* the view data does not match the expected type
|
|
|
|
* according to {@link FormConfigInterface::getDataClass}.
|
2011-05-10 14:32:14 +01:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function setData($modelData);
|
2011-03-25 09:54:04 +00:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
|
|
|
* Returns the data in the format needed for the underlying object.
|
|
|
|
*
|
|
|
|
* @return mixed
|
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function getData();
|
2011-03-22 22:20:14 +00:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
|
|
|
* Returns the normalized data of the field.
|
|
|
|
*
|
2016-06-28 06:50:50 +01:00
|
|
|
* @return mixed When the field is not submitted, the default data is returned
|
2013-04-20 16:32:55 +01:00
|
|
|
* When the field is submitted, the normalized submitted data is
|
2012-08-26 07:28:19 +01:00
|
|
|
* returned if the field is valid, null otherwise.
|
2011-05-10 14:32:14 +01:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function getNormData();
|
2011-05-04 15:58:39 +01:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
|
|
|
* Returns the data transformed by the value transformer.
|
|
|
|
*
|
2012-08-26 07:28:19 +01:00
|
|
|
* @return mixed
|
2011-05-10 14:32:14 +01:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function getViewData();
|
2011-03-22 22:20:14 +00:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
|
|
|
* Returns the extra data.
|
|
|
|
*
|
2013-04-20 16:32:55 +01:00
|
|
|
* @return array The submitted data which do not belong to a child
|
2011-05-10 14:32:14 +01:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function getExtraData();
|
2011-05-10 14:32:14 +01:00
|
|
|
|
|
|
|
/**
|
2012-05-17 15:09:13 +01:00
|
|
|
* Returns the form's configuration.
|
2011-05-10 14:32:14 +01:00
|
|
|
*
|
2016-06-28 06:50:50 +01:00
|
|
|
* @return FormConfigInterface The configuration
|
2011-05-10 14:32:14 +01:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function getConfig();
|
2011-03-25 09:54:04 +00:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
2012-12-31 14:29:36 +00:00
|
|
|
* Returns whether the form is submitted.
|
2011-05-10 14:32:14 +01:00
|
|
|
*
|
2014-11-30 13:33:44 +00:00
|
|
|
* @return bool true if the form is submitted, false otherwise
|
2011-05-10 14:32:14 +01:00
|
|
|
*/
|
2013-04-20 16:32:55 +01:00
|
|
|
public function isSubmitted();
|
2011-03-24 21:20:54 +00:00
|
|
|
|
2011-03-20 12:35:19 +00:00
|
|
|
/**
|
|
|
|
* Returns the name by which the form is identified in forms.
|
|
|
|
*
|
2016-06-28 06:50:50 +01:00
|
|
|
* @return string The name of the form
|
2011-03-20 12:35:19 +00:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function getName();
|
2011-03-20 12:35:19 +00:00
|
|
|
|
2012-05-17 15:09:13 +01:00
|
|
|
/**
|
|
|
|
* Returns the property path that the form is mapped to.
|
|
|
|
*
|
2016-06-28 06:50:50 +01:00
|
|
|
* @return \Symfony\Component\PropertyAccess\PropertyPathInterface The property path
|
2012-05-17 15:09:13 +01:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function getPropertyPath();
|
2012-05-17 15:09:13 +01:00
|
|
|
|
2011-03-20 12:35:19 +00:00
|
|
|
/**
|
2011-05-10 14:32:14 +01:00
|
|
|
* Adds an error to this form.
|
2011-03-20 12:35:19 +00:00
|
|
|
*
|
2014-11-30 13:33:44 +00:00
|
|
|
* @param FormError $error
|
2012-05-20 10:18:31 +01:00
|
|
|
*
|
2016-12-26 07:50:27 +00:00
|
|
|
* @return $this
|
2011-03-20 12:35:19 +00:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function addError(FormError $error);
|
2011-03-20 12:35:19 +00:00
|
|
|
|
|
|
|
/**
|
2012-08-26 20:36:01 +01:00
|
|
|
* Returns whether the form and all children are valid.
|
2011-03-20 12:35:19 +00:00
|
|
|
*
|
2013-04-20 16:32:55 +01:00
|
|
|
* If the form is not submitted, this method always returns false.
|
2012-12-30 15:38:36 +00:00
|
|
|
*
|
2014-04-16 11:30:19 +01:00
|
|
|
* @return bool
|
2011-03-20 12:35:19 +00:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function isValid();
|
2011-03-20 12:35:19 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* 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.
|
|
|
|
*
|
2014-04-16 11:30:19 +01:00
|
|
|
* @return bool
|
2011-03-20 12:35:19 +00:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function isRequired();
|
2011-03-20 12:35:19 +00:00
|
|
|
|
|
|
|
/**
|
2012-01-26 15:54:42 +00:00
|
|
|
* Returns whether this form is disabled.
|
2011-03-20 12:35:19 +00:00
|
|
|
*
|
2012-01-26 15:54:42 +00:00
|
|
|
* The content of a disabled form is displayed, but not allowed to be
|
|
|
|
* modified. The validation of modified disabled forms should fail.
|
2011-03-20 12:35:19 +00:00
|
|
|
*
|
2012-04-13 15:06:32 +01:00
|
|
|
* Forms whose parents are disabled are considered disabled regardless of
|
2011-03-20 12:35:19 +00:00
|
|
|
* their own state.
|
|
|
|
*
|
2014-04-16 11:30:19 +01:00
|
|
|
* @return bool
|
2011-03-20 12:35:19 +00:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function isDisabled();
|
2011-03-20 12:35:19 +00:00
|
|
|
|
|
|
|
/**
|
2011-05-10 14:32:14 +01:00
|
|
|
* Returns whether the form is empty.
|
2011-03-20 12:35:19 +00:00
|
|
|
*
|
2014-04-16 11:30:19 +01:00
|
|
|
* @return bool
|
2011-03-20 12:35:19 +00:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function isEmpty();
|
2011-03-20 12:35:19 +00:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
|
|
|
* Returns whether the data in the different formats is synchronized.
|
|
|
|
*
|
2014-09-26 12:06:33 +01:00
|
|
|
* If the data is not synchronized, you can get the transformation failure
|
|
|
|
* by calling {@link getTransformationFailure()}.
|
|
|
|
*
|
2014-04-16 11:30:19 +01:00
|
|
|
* @return bool
|
2011-05-10 14:32:14 +01:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function isSynchronized();
|
2011-03-25 09:54:04 +00:00
|
|
|
|
2014-09-26 12:06:33 +01:00
|
|
|
/**
|
|
|
|
* Returns the data transformation failure, if any.
|
|
|
|
*
|
|
|
|
* @return TransformationFailedException|null The transformation failure
|
|
|
|
*/
|
|
|
|
public function getTransformationFailure();
|
|
|
|
|
2012-12-30 15:38:36 +00:00
|
|
|
/**
|
2013-04-29 16:31:30 +01:00
|
|
|
* Initializes the form tree.
|
2012-12-30 15:38:36 +00:00
|
|
|
*
|
2013-04-29 16:31:30 +01:00
|
|
|
* Should be called on the root form after constructing the tree.
|
2012-12-30 15:38:36 +00:00
|
|
|
*
|
2016-12-26 07:50:27 +00:00
|
|
|
* @return $this
|
2013-04-29 16:31:30 +01:00
|
|
|
*/
|
|
|
|
public function initialize();
|
|
|
|
|
|
|
|
/**
|
|
|
|
* 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.
|
|
|
|
*
|
2016-06-28 06:50:50 +01:00
|
|
|
* @param mixed $request The request to handle
|
2012-12-30 15:38:36 +00:00
|
|
|
*
|
2016-12-26 07:50:27 +00:00
|
|
|
* @return $this
|
2012-12-30 15:38:36 +00:00
|
|
|
*/
|
2013-04-20 14:56:42 +01:00
|
|
|
public function handleRequest($request = null);
|
2012-12-30 15:38:36 +00:00
|
|
|
|
2011-03-20 12:35:19 +00:00
|
|
|
/**
|
2013-04-20 16:32:55 +01:00
|
|
|
* Submits data to the form, transforms and validates it.
|
2011-03-20 12:35:19 +00:00
|
|
|
*
|
2016-06-28 06:50:50 +01:00
|
|
|
* @param null|string|array $submittedData The submitted data
|
2014-04-12 18:54:57 +01:00
|
|
|
* @param bool $clearMissing Whether to set fields to NULL
|
2013-04-25 15:08:09 +01:00
|
|
|
* when they are missing in the
|
|
|
|
* submitted data.
|
2012-05-20 10:18:31 +01:00
|
|
|
*
|
2016-12-26 07:50:27 +00:00
|
|
|
* @return $this
|
2012-08-26 07:28:19 +01:00
|
|
|
*
|
2013-04-20 16:32:55 +01:00
|
|
|
* @throws Exception\AlreadySubmittedException If the form has already been submitted.
|
2011-03-20 12:35:19 +00:00
|
|
|
*/
|
2013-04-25 15:08:09 +01:00
|
|
|
public function submit($submittedData, $clearMissing = true);
|
2011-03-22 00:40:02 +00:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
|
|
|
* Returns the root of the form tree.
|
|
|
|
*
|
2016-12-26 07:50:27 +00:00
|
|
|
* @return self The root of the tree
|
2011-05-10 14:32:14 +01:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function getRoot();
|
2011-03-31 14:23:33 +01:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
|
|
|
* Returns whether the field is the root of the form tree.
|
|
|
|
*
|
2014-04-16 11:30:19 +01:00
|
|
|
* @return bool
|
2011-05-10 14:32:14 +01:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function isRoot();
|
2011-04-13 08:31:11 +01:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
|
|
|
* Creates a view.
|
|
|
|
*
|
2012-07-16 13:57:09 +01:00
|
|
|
* @param FormView $parent The parent view
|
2011-05-10 14:32:14 +01:00
|
|
|
*
|
2012-07-16 13:57:09 +01:00
|
|
|
* @return FormView The view
|
2011-05-10 14:32:14 +01:00
|
|
|
*/
|
2012-07-16 13:57:09 +01:00
|
|
|
public function createView(FormView $parent = null);
|
2011-03-24 21:20:54 +00:00
|
|
|
}
|