diff --git a/CHANGELOG-2.1.md b/CHANGELOG-2.1.md
index 7e1cfe65fc..5dbe07a044 100644
--- a/CHANGELOG-2.1.md
+++ b/CHANGELOG-2.1.md
@@ -168,7 +168,7 @@ To get the diff between two versions, go to https://github.com/symfony/symfony/c
* [BC BREAK] greatly improved `ChoiceListInterface` and all of its
implementations. `EntityChoiceList` was adapted, the methods `getEntities()`,
- `getEntitiesByByKeys()`, `getIdentifier()` and `getIdentifierValues()` were
+ `getEntitiesByKeys()`, `getIdentifier()` and `getIdentifierValues()` were
removed/made private. Instead of the first two you can use `getChoices()`
and `getChoicesByValues()`, for the latter two no replacement exists.
`ArrayChoiceList` was replaced by `SimpleChoiceList`.
diff --git a/UPGRADE-2.1.md b/UPGRADE-2.1.md
index 601b18b452..7439f0eb10 100644
--- a/UPGRADE-2.1.md
+++ b/UPGRADE-2.1.md
@@ -92,12 +92,12 @@ UPGRADE FROM 2.0 to 2.1
choice field has changed
Instead of using the choice value, a generated integer is now stored.
- Again, take care if your Javascript reads this value. If your choice field
- is a non-expanded single-choice field, or if the choices are guaranteed not
- to contain the empty string '' (which is the case when you added it manually
- or when the field is a single-choice field and is not required), you can
- restore the old behaviour by setting the option "value_strategy" to
- `ChoiceList::COPY_CHOICE`.
+ Again, take care if your Javascript reads this value. If your choice field
+ is a non-expanded single-choice field, or if the choices are guaranteed not
+ to contain the empty string '' (which is the case when you added it manually
+ or when the field is a single-choice field and is not required), you can
+ restore the old behaviour by setting the option "value_strategy" to
+ `ChoiceList::COPY_CHOICE`.
* In the template of the choice type, the structure of the "choices" variable
has changed
diff --git a/src/Symfony/Bridge/Doctrine/Form/ChoiceList/EntityChoiceList.php b/src/Symfony/Bridge/Doctrine/Form/ChoiceList/EntityChoiceList.php
index c1fe98245a..ee8019a0fd 100644
--- a/src/Symfony/Bridge/Doctrine/Form/ChoiceList/EntityChoiceList.php
+++ b/src/Symfony/Bridge/Doctrine/Form/ChoiceList/EntityChoiceList.php
@@ -73,8 +73,10 @@ class EntityChoiceList extends ObjectChoiceList
* @param string $class The class name
* @param string $labelPath The property path used for the label
* @param EntityLoaderInterface $entityLoader An optional query builder
- * @param array $entities An array of choices
- * @param string $groupPath
+ * @param array $entities An array of choices
+ * @param string $groupPath A property path pointing to the property used
+ * to group the choices. Only allowed if
+ * the choices are given as flat array.
*/
public function __construct(ObjectManager $manager, $class, $labelPath = null, EntityLoaderInterface $entityLoader = null, $entities = null, $groupPath = null)
{
diff --git a/src/Symfony/Bridge/Doctrine/Form/ChoiceList/EntityLoaderInterface.php b/src/Symfony/Bridge/Doctrine/Form/ChoiceList/EntityLoaderInterface.php
index 4fc8e6ba99..ea459a6487 100644
--- a/src/Symfony/Bridge/Doctrine/Form/ChoiceList/EntityLoaderInterface.php
+++ b/src/Symfony/Bridge/Doctrine/Form/ChoiceList/EntityLoaderInterface.php
@@ -21,17 +21,19 @@ interface EntityLoaderInterface
/**
* Returns an array of entities that are valid choices in the corresponding choice list.
*
- * @return array
+ * @return array The entities.
*/
function getEntities();
/**
* Returns an array of entities matching the given identifiers.
*
- * @param string $identifier
- * @param array $values
+ * @param string $identifier The identifier field of the object. This method
+ * is not applicable for fields with multiple
+ * identifiers.
+ * @param array $values The values of the identifiers.
*
- * @return array
+ * @return array The entities.
*/
function getEntitiesByIds($identifier, array $values);
}
diff --git a/src/Symfony/Component/Form/Extension/Core/ChoiceList/ChoiceListInterface.php b/src/Symfony/Component/Form/Extension/Core/ChoiceList/ChoiceListInterface.php
index 206727dde3..122b50e7e5 100644
--- a/src/Symfony/Component/Form/Extension/Core/ChoiceList/ChoiceListInterface.php
+++ b/src/Symfony/Component/Form/Extension/Core/ChoiceList/ChoiceListInterface.php
@@ -51,6 +51,20 @@ interface ChoiceListInterface
* Returns the choice views of the preferred choices as nested array with
* the choice groups as top-level keys.
*
+ * Example:
+ *
+ *
+ * array(
+ * 'Group 1' => array(
+ * 10 => ChoiceView object,
+ * 20 => ChoiceView object,
+ * ),
+ * 'Group 2' => array(
+ * 30 => ChoiceView object,
+ * ),
+ * )
+ *
+ *
* @return array A nested array containing the views with the corresponding
* choice indices as keys on the lowest levels and the choice
* group names in the keys of the higher levels.
@@ -61,6 +75,20 @@ interface ChoiceListInterface
* Returns the choice views of the choices that are not preferred as nested
* array with the choice groups as top-level keys.
*
+ * Example:
+ *
+ *
+ * array(
+ * 'Group 1' => array(
+ * 10 => ChoiceView object,
+ * 20 => ChoiceView object,
+ * ),
+ * 'Group 2' => array(
+ * 30 => ChoiceView object,
+ * ),
+ * )
+ *
+ *
* @return array A nested array containing the views with the corresponding
* choice indices as keys on the lowest levels and the choice
* group names in the keys of the higher levels.
diff --git a/src/Symfony/Component/Form/Extension/Core/ChoiceList/SimpleChoiceList.php b/src/Symfony/Component/Form/Extension/Core/ChoiceList/SimpleChoiceList.php
index 16845d648d..f59827e7d8 100644
--- a/src/Symfony/Component/Form/Extension/Core/ChoiceList/SimpleChoiceList.php
+++ b/src/Symfony/Component/Form/Extension/Core/ChoiceList/SimpleChoiceList.php
@@ -120,12 +120,12 @@ class SimpleChoiceList extends ChoiceList
/**
- * Converts the choices to a valid PHP array keys.
+ * Converts the choices to valid PHP array keys.
*
- * @param array $choices The choices.
- *
- * @return array Valid PHP array keys.
- */
+ * @param array $choices The choices.
+ *
+ * @return array Valid PHP array keys.
+ */
protected function fixChoices(array $choices)
{
return $this->fixIndices($choices);
diff --git a/src/Symfony/Component/Form/Extension/Core/DataTransformer/ChoiceToValueTransformer.php b/src/Symfony/Component/Form/Extension/Core/DataTransformer/ChoiceToValueTransformer.php
index e63e0f1941..13d90a9151 100644
--- a/src/Symfony/Component/Form/Extension/Core/DataTransformer/ChoiceToValueTransformer.php
+++ b/src/Symfony/Component/Form/Extension/Core/DataTransformer/ChoiceToValueTransformer.php
@@ -53,7 +53,7 @@ class ChoiceToValueTransformer implements DataTransformerInterface
$choices = $this->choiceList->getChoicesForValues(array($value));
if (count($choices) !== 1) {
- throw new TransformationFailedException('The choice "' . $value . '" does not exist');
+ throw new TransformationFailedException('The choice "' . $value . '" does not exist or is not unique');
}
$choice = current($choices);