symfony · fabpot · Jan 31, 2012 · Jan 30, 2012 · Jan 30, 2012 · Jan 30, 2012
diff --git a/CHANGELOG-2.1.md b/CHANGELOG-2.1.md
@@ -166,43 +166,30 @@ To get the diff between two versions, go to https://github.com/symfony/symfony/c
  * allowed setting different options for RepeatedType fields (like the label)
  * added support for empty form name at root level, this enables rendering forms
    without form name prefix in field names
-
- * [BC BREAK] made form naming more restrictive. Form and field names must
-   start with a letter, digit or underscore and only contain letters, digits,
-   underscores, hyphens and colons
-
+ * [BC BREAK] form and field names must start with a letter, digit or underscore
+   and only contain letters, digits, underscores, hyphens and colons
  * [BC BREAK] changed default name of the prototype in the "collection" type
    from "$$name$$" to "__name__". No dollars are appended/prepended to custom
    names anymore.
-
- * [BC BREAK] greatly improved `ChoiceListInterface` and all of its
-   implementations. `EntityChoiceList` was adapted, the methods `getEntities()`,
-   `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`.
-   `PaddedChoiceList`, `MonthChoiceList` and `TimezoneChoiceList` were removed.
-   Their functionality was merged into `DateType`, `TimeType` and `TimezoneType`.
-
- * [BC BREAK] removed `EntitiesToArrayTransformer` and `EntityToIdTransformer`.
-   The former has been replaced by `CollectionToArrayTransformer` in combination
-   with `EntityChoiceList`, the latter is not required in the core anymore.
+ * [BC BREAK] improved ChoiceListInterface and all of its implementations
+ * [BC BREAK] removed EntitiesToArrayTransformer and EntityToIdTransformer.
+   The former has been replaced by CollectionToArrayTransformer in combination
+   with EntityChoiceList, the latter is not required in the core anymore.
 
  * [BC BREAK] renamed
 
-   * `ArrayToBooleanChoicesTransformer` to `ChoicesToBooleanArrayTransformer`
-   * `ScalarToBooleanChoicesTransformer` to `ChoiceToBooleanArrayTransformer`
-   * `ArrayToChoicesTransformer` to `ChoicesToValuesTransformer`
-   * `ScalarToChoiceTransformer` to `ChoiceToValueTransformer`
-
-   to be consistent with the naming in `ChoiceListInterface`.
+   * ArrayToBooleanChoicesTransformer to ChoicesToBooleanArrayTransformer
+   * ScalarToBooleanChoicesTransformer to ChoiceToBooleanArrayTransformer
+   * ArrayToChoicesTransformer to ChoicesToValuesTransformer
+   * ScalarToChoiceTransformer to ChoiceToValueTransformer
 
- * [BC BREAK] removed `FormUtil::toArrayKey()` and `FormUtil::toArrayKeys()`.
-   They were merged into `ChoiceList` and have no public equivalent anymore.
+   to be consistent with the naming in ChoiceListInterface.
 
- * added `ComplexChoiceList` and `ObjectChoiceList`. Both let you select amongst
+ * [BC BREAK] removed FormUtil::toArrayKey() and FormUtil::toArrayKeys().
+   They were merged into ChoiceList and have no public equivalent anymore.
+ * added ComplexChoiceList and ObjectChoiceList. Both let you select amongst
    objects in a choice field, but feature different constructors.
- * choice fields now throw a `FormException` if neither the "choices" nor the
+ * choice fields now throw a FormException if neither the "choices" nor the
    "choice_list" option is set
  * the radio field is now a child type of the checkbox field
 

diff --git a/UPGRADE-2.1.md b/UPGRADE-2.1.md
@@ -78,6 +78,60 @@ UPGRADE FROM 2.0 to 2.1
     enable BC behaviour by setting the option "cascade_validation" to `true` on
     the parent form.
 
+* Changed implementation of choice lists
+
+    ArrayChoiceList was replaced. If you have custom classes that extend
+    this class, you can now extend SimpleChoiceList.
+
+    Before:
+
+        class MyChoiceList extends ArrayChoiceList
+        {
+            protected function load()
+            {
+                parent::load();
+
+                // load choices
+
+                $this->choices = $choices;
+            }
+        }
+
+    After:
+
+        class MyChoiceList extends SimpleChoiceList
+        {
+            public function __construct()
+            {
+                // load choices
+
+                parent::__construct($choices);
+            }
+        }
+
+    If you need to load the choices lazily - that is, as soon as they are
+    accessed for the first time -  you can extend LazyChoiceList instead.
+
+        class MyChoiceList extends LazyChoiceList
+        {
+            protected function loadChoiceList()
+            {
+                // load choices
+
+                return new SimpleChoiceList($choices);
+            }
+        }
+
+    PaddedChoiceList, MonthChoiceList and TimezoneChoiceList were removed.
+    Their functionality was merged into DateType, TimeType and
+    TimezoneType.
+
+    EntityChoiceList was adapted. The methods `getEntities`,
+    `getEntitiesByKeys`, `getIdentifier` and `getIdentifierValues` were
+    removed/made private. Instead of the first two, you can now use
+    `getChoices` and `getChoicesByValues`. For the latter two, no
+    replacement exists.
+
 * The strategy for generating the HTML attributes "id" and "name"
   of choices in a choice field has changed
 
@@ -102,8 +156,8 @@ UPGRADE FROM 2.0 to 2.1
 * In the template of the choice type, the structure of the "choices" variable
   has changed
 
-    "choices" now contains ChoiceView objects with two getters `getValue()`
-    and `getLabel()` to access the choice data. The indices of the array
+    "choices" now contains ChoiceView objects with two getters `getValue`
+    and `getLabel` to access the choice data. The indices of the array
     store an index whose generation is controlled by the "index_generation"
     option of the choice field.
 

diff --git a/src/Symfony/Component/Form/Extension/Core/ChoiceList/ChoiceList.php b/src/Symfony/Component/Form/Extension/Core/ChoiceList/ChoiceList.php
@@ -17,7 +17,16 @@
 use Symfony\Component\Form\Extension\Core\View\ChoiceView;
 
 /**
- * Base class for choice list implementations.
+ * A choice list for choices of arbitrary data types.
+ *
+ * Choices and labels are passed in two arrays. The indices of the choices
+ * and the labels should match.
+ *
+ * <code>
+ * $choices = array(true, false);
+ * $labels = array('Agree', 'Disagree');
+ * $choiceList = new ChoiceList($choices, $labels);
+ * </code>
  *
  * @author Bernhard Schussek <bschussek@gmail.<com>
  */
@@ -145,63 +154,39 @@ protected function initialize($choices, array $labels, array $preferredChoices)
     }
 
     /**
-     * Returns the list of choices
-     *
-     * @return array
-     *
-     * @see Symfony\Component\Form\Extension\Core\ChoiceList\ChoiceListInterface
+     * {@inheritdoc}
      */
     public function getChoices()
     {
         return $this->choices;
     }
 
     /**
-     * Returns the values for the choices
-     *
-     * @return array
-     *
-     * @see Symfony\Component\Form\Extension\Core\ChoiceList\ChoiceListInterface
+     * {@inheritdoc}
      */
     public function getValues()
     {
         return $this->values;
     }
 
     /**
-     * Returns the choice views of the preferred choices as nested array with
-     * the choice groups as top-level keys.
-     *
-     * @return array
-     *
-     * @see Symfony\Component\Form\Extension\Core\ChoiceList\ChoiceListInterface
+     * {@inheritdoc}
      */
     public function getPreferredViews()
     {
         return $this->preferredViews;
     }
 
     /**
-     * Returns the choice views of the choices that are not preferred as nested
-     * array with the choice groups as top-level keys.
-     *
-     * @return array
-     *
-     * @see Symfony\Component\Form\Extension\Core\ChoiceList\ChoiceListInterface
+     * {@inheritdoc}
      */
     public function getRemainingViews()
     {
         return $this->remainingViews;
     }
 
     /**
-     * Returns the choices corresponding to the given values.
-     *
-     * @param array $values
-     *
-     * @return array
-     *
-     * @see Symfony\Component\Form\Extension\Core\ChoiceList\ChoiceListInterface
+     * {@inheritdoc}
      */
     public function getChoicesForValues(array $values)
     {
@@ -232,13 +217,7 @@ public function getChoicesForValues(array $values)
     }
 
     /**
-     * Returns the values corresponding to the given choices.
-     *
-     * @param array $choices
-     *
-     * @return array
-     *
-     * @see Symfony\Component\Form\Extension\Core\ChoiceList\ChoiceListInterface
+     * {@inheritdoc}
      */
     public function getValuesForChoices(array $choices)
     {
@@ -269,13 +248,7 @@ public function getValuesForChoices(array $choices)
     }
 
     /**
-     * Returns the indices corresponding to the given choices.
-     *
-     * @param array $choices
-     *
-     * @return array
-     *
-     * @see Symfony\Component\Form\Extension\Core\ChoiceList\ChoiceListInterface
+     * {@inheritdoc}
      */
     public function getIndicesForChoices(array $choices)
     {
@@ -299,13 +272,7 @@ public function getIndicesForChoices(array $choices)
     }
 
     /**
-     * Returns the indices corresponding to the given values.
-     *
-     * @param array $values
-     *
-     * @return array
-     *
-     * @see Symfony\Component\Form\Extension\Core\ChoiceList\ChoiceListInterface
+     * {@inheritdoc}
      */
     public function getIndicesForValues(array $values)
     {