From a676598d74195da6558b8e6060825773f6f0f3f9 Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Mon, 30 Jan 2012 10:56:58 +0100 Subject: [PATCH 1/6] [Form] Added class LazyChoiceList --- .../Core/ChoiceList/LazyChoiceList.php | 214 ++++++++++++++++++ .../Core/ChoiceList/LazyChoiceListTest.php | 116 ++++++++++ 2 files changed, 330 insertions(+) create mode 100644 src/Symfony/Component/Form/Extension/Core/ChoiceList/LazyChoiceList.php create mode 100644 tests/Symfony/Tests/Component/Form/Extension/Core/ChoiceList/LazyChoiceListTest.php diff --git a/src/Symfony/Component/Form/Extension/Core/ChoiceList/LazyChoiceList.php b/src/Symfony/Component/Form/Extension/Core/ChoiceList/LazyChoiceList.php new file mode 100644 index 0000000000..8a83ec833d --- /dev/null +++ b/src/Symfony/Component/Form/Extension/Core/ChoiceList/LazyChoiceList.php @@ -0,0 +1,214 @@ + + * + * For the full copyright and license information, please view the LICENSE + * file that was distributed with this source code. + */ + +namespace Symfony\Component\Form\Extension\Core\ChoiceList; + +use Symfony\Component\Form\Exception\FormException; + +/** + * A choice list that is loaded lazily + * + * This list loads itself as soon as any of the getters is accessed for the + * first time. You should implement loadChoiceList() in your child classes, + * which should return a ChoiceListInterface instance. + * + * @author Bernhard Schussek + */ +abstract class LazyChoiceList implements ChoiceListInterface +{ + /** + * The loaded choice list + * + * @var ChoiceListInterface + */ + private $choiceList; + + /** + * Returns the list of choices + * + * @return array The choices with their indices as keys. + */ + public function getChoices() + { + if (!$this->choiceList) { + $this->load(); + } + + return $this->choiceList->getChoices(); + } + + /** + * Returns the values for the choices + * + * @return array The values with the corresponding choice indices as keys. + */ + public function getValues() + { + if (!$this->choiceList) { + $this->load(); + } + + return $this->choiceList->getValues(); + } + + /** + * 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. + */ + public function getPreferredViews() + { + if (!$this->choiceList) { + $this->load(); + } + + return $this->choiceList->getPreferredViews(); + } + + /** + * 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. + * + * @see getPreferredValues + */ + public function getRemainingViews() + { + if (!$this->choiceList) { + $this->load(); + } + + return $this->choiceList->getRemainingViews(); + } + + /** + * Returns the choices corresponding to the given values. + * + * @param array $values An array of choice values. Not existing values in + * this array are ignored. + * + * @return array An array of choices with ascending, 0-based numeric keys + */ + public function getChoicesForValues(array $values) + { + if (!$this->choiceList) { + $this->load(); + } + + return $this->choiceList->getChoicesForValues($values); + } + + /** + * Returns the values corresponding to the given choices. + * + * @param array $choices An array of choices. Not existing choices in this + * array are ignored. + * + * @return array An array of choice values with ascending, 0-based numeric + * keys + */ + public function getValuesForChoices(array $choices) + { + if (!$this->choiceList) { + $this->load(); + } + + return $this->choiceList->getValuesForChoices($choices); + } + + /** + * Returns the indices corresponding to the given choices. + * + * @param array $choices An array of choices. Not existing choices in this + * array are ignored. + * + * @return array An array of indices with ascending, 0-based numeric keys + */ + public function getIndicesForChoices(array $choices) + { + if (!$this->choiceList) { + $this->load(); + } + + return $this->choiceList->getIndicesForChoices($choices); + } + + /** + * Returns the indices corresponding to the given values. + * + * @param array $values An array of choice values. Not existing values in + * this array are ignored. + * + * @return array An array of indices with ascending, 0-based numeric keys + */ + public function getIndicesForValues(array $values) + { + if (!$this->choiceList) { + $this->load(); + } + + return $this->choiceList->getIndicesForValues($values); + } + + /** + * Loads the choice list + * + * Should be implemented by child classes. + * + * @return ChoiceListInterface The loaded choice list + */ + abstract protected function loadChoiceList(); + + private function load() + { + $choiceList = $this->loadChoiceList(); + + if (!$choiceList instanceof ChoiceListInterface) { + throw new FormException('loadChoiceList() should return a ChoiceListInterface instance. Got ' . gettype($choiceList)); + } + + $this->choiceList = $choiceList; + } +} \ No newline at end of file diff --git a/tests/Symfony/Tests/Component/Form/Extension/Core/ChoiceList/LazyChoiceListTest.php b/tests/Symfony/Tests/Component/Form/Extension/Core/ChoiceList/LazyChoiceListTest.php new file mode 100644 index 0000000000..6e6bb927dc --- /dev/null +++ b/tests/Symfony/Tests/Component/Form/Extension/Core/ChoiceList/LazyChoiceListTest.php @@ -0,0 +1,116 @@ + + * + * For the full copyright and license information, please view the LICENSE + * file that was distributed with this source code. + */ + +namespace Symfony\Tests\Component\Form\Extension\Core\ChoiceList; + +use Symfony\Component\Form\Extension\Core\ChoiceList\SimpleChoiceList; +use Symfony\Component\Form\Extension\Core\ChoiceList\LazyChoiceList; +use Symfony\Component\Form\Extension\Core\View\ChoiceView; + +class LazyChoiceListTest extends \PHPUnit_Framework_TestCase +{ + private $list; + + protected function setUp() + { + parent::setUp(); + + $this->list = new LazyChoiceListTest_Impl(new SimpleChoiceList(array( + 'a' => 'A', + 'b' => 'B', + 'c' => 'C', + ), array('b'))); + } + + protected function tearDown() + { + parent::tearDown(); + + $this->list = null; + } + + public function testGetChoices() + { + $this->assertSame(array(0 => 'a', 1 => 'b', 2 => 'c'), $this->list->getChoices()); + } + + public function testGetValues() + { + $this->assertSame(array(0 => 'a', 1 => 'b', 2 => 'c'), $this->list->getValues()); + } + + public function testGetPreferredViews() + { + $this->assertEquals(array(1 => new ChoiceView('b', 'B')), $this->list->getPreferredViews()); + } + + public function testGetRemainingViews() + { + $this->assertEquals(array(0 => new ChoiceView('a', 'A'), 2 => new ChoiceView('c', 'C')), $this->list->getRemainingViews()); + } + + public function testGetIndicesForChoices() + { + $choices = array('b', 'c'); + $this->assertSame(array(1, 2), $this->list->getIndicesForChoices($choices)); + } + + public function testGetIndicesForValues() + { + $values = array('b', 'c'); + $this->assertSame(array(1, 2), $this->list->getIndicesForValues($values)); + } + + public function testGetChoicesForValues() + { + $values = array('b', 'c'); + $this->assertSame(array('b', 'c'), $this->list->getChoicesForValues($values)); + } + + public function testGetValuesForChoices() + { + $choices = array('b', 'c'); + $this->assertSame(array('b', 'c'), $this->list->getValuesForChoices($choices)); + } + + /** + * @expectedException Symfony\Component\Form\Exception\FormException + */ + public function testLoadChoiceListShouldReturnChoiceList() + { + $list = new LazyChoiceListTest_InvalidImpl(); + + $list->getChoices(); + } +} + +class LazyChoiceListTest_Impl extends LazyChoiceList +{ + private $choiceList; + + public function __construct($choiceList) + { + $this->choiceList = $choiceList; + } + + protected function loadChoiceList() + { + return $this->choiceList; + } +} + +class LazyChoiceListTest_InvalidImpl extends LazyChoiceList +{ + protected function loadChoiceList() + { + return new \stdClass(); + } +} \ No newline at end of file From d346ae6a8ff89ef344140b8646822fdf82d2bcff Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Mon, 30 Jan 2012 10:57:14 +0100 Subject: [PATCH 2/6] Improved choice list sections of UPGRADE and CHANGELOG --- CHANGELOG-2.1.md | 43 +++++++++++++++---------------------------- UPGRADE-2.1.md | 21 +++++++++++++++++++-- 2 files changed, 34 insertions(+), 30 deletions(-) diff --git a/CHANGELOG-2.1.md b/CHANGELOG-2.1.md index f51c9827ea..b74f2b228a 100644 --- 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` + * ArrayToBooleanChoicesTransformer to ChoicesToBooleanArrayTransformer + * ScalarToBooleanChoicesTransformer to ChoiceToBooleanArrayTransformer + * ArrayToChoicesTransformer to ChoicesToValuesTransformer + * ScalarToChoiceTransformer to ChoiceToValueTransformer - to be consistent with the naming in `ChoiceListInterface`. + to be consistent with the naming in ChoiceListInterface. - * [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 + * [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 index 9b79eb32ae..dbd2b3f6b5 100644 --- a/UPGRADE-2.1.md +++ b/UPGRADE-2.1.md @@ -78,6 +78,23 @@ 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 + ArrayChoiceList and load the choices in the constructor, you can extend + SimpleChoiceList instead. If choices are loaded lazily, you should extend + LazyChoiceList and implement its `loadChoiceList` method. + + 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 +119,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. From 7899bea3e585fa0cc2e2c037c3ba38da2ea3d01b Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Mon, 30 Jan 2012 11:10:25 +0100 Subject: [PATCH 3/6] Added examples to UPGRADE --- UPGRADE-2.1.md | 43 ++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 40 insertions(+), 3 deletions(-) diff --git a/UPGRADE-2.1.md b/UPGRADE-2.1.md index dbd2b3f6b5..a46451ee8e 100644 --- a/UPGRADE-2.1.md +++ b/UPGRADE-2.1.md @@ -81,9 +81,46 @@ UPGRADE FROM 2.0 to 2.1 * Changed implementation of choice lists ArrayChoiceList was replaced. If you have custom classes that extend - ArrayChoiceList and load the choices in the constructor, you can extend - SimpleChoiceList instead. If choices are loaded lazily, you should extend - LazyChoiceList and implement its `loadChoiceList` method. + this class, you can now extend SimpleChoiceList. + + Before: + + class MyChoiceList extends ArrayChoicList + { + protected function load() + { + parent::load(); + + // load choices + + $this->choices = $choices; + } + } + + After: + + class MyChoiceList extends SimpleChoicList + { + 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 From 2c530cc236f07a427aafc69fcd9be4a066a00e46 Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Mon, 30 Jan 2012 13:36:34 +0100 Subject: [PATCH 4/6] Fixed typos in UPGRADE file --- UPGRADE-2.1.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/UPGRADE-2.1.md b/UPGRADE-2.1.md index a46451ee8e..120e66e933 100644 --- a/UPGRADE-2.1.md +++ b/UPGRADE-2.1.md @@ -85,7 +85,7 @@ UPGRADE FROM 2.0 to 2.1 Before: - class MyChoiceList extends ArrayChoicList + class MyChoiceList extends ArrayChoiceList { protected function load() { @@ -99,7 +99,7 @@ UPGRADE FROM 2.0 to 2.1 After: - class MyChoiceList extends SimpleChoicList + class MyChoiceList extends SimpleChoiceList { public function __construct() { From 9e7e2af08762a6ea356ae507ea917e5b56029346 Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Mon, 30 Jan 2012 18:21:53 +0100 Subject: [PATCH 5/6] [Form] Fixed PHPDoc: Used {@inheritdoc} where applicable --- .../Extension/Core/ChoiceList/ChoiceList.php | 58 ++--------- .../Core/ChoiceList/LazyChoiceList.php | 97 +++---------------- 2 files changed, 24 insertions(+), 131 deletions(-) diff --git a/src/Symfony/Component/Form/Extension/Core/ChoiceList/ChoiceList.php b/src/Symfony/Component/Form/Extension/Core/ChoiceList/ChoiceList.php index c8cd44ccd8..d38c32bc79 100644 --- a/src/Symfony/Component/Form/Extension/Core/ChoiceList/ChoiceList.php +++ b/src/Symfony/Component/Form/Extension/Core/ChoiceList/ChoiceList.php @@ -145,11 +145,7 @@ class ChoiceList implements ChoiceListInterface } /** - * Returns the list of choices - * - * @return array - * - * @see Symfony\Component\Form\Extension\Core\ChoiceList\ChoiceListInterface + * {@inheritdoc} */ public function getChoices() { @@ -157,11 +153,7 @@ class ChoiceList implements ChoiceListInterface } /** - * Returns the values for the choices - * - * @return array - * - * @see Symfony\Component\Form\Extension\Core\ChoiceList\ChoiceListInterface + * {@inheritdoc} */ public function getValues() { @@ -169,12 +161,7 @@ class ChoiceList implements ChoiceListInterface } /** - * 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() { @@ -182,12 +169,7 @@ class ChoiceList implements ChoiceListInterface } /** - * 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() { @@ -195,13 +177,7 @@ class ChoiceList implements ChoiceListInterface } /** - * 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 +208,7 @@ class ChoiceList implements ChoiceListInterface } /** - * 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 +239,7 @@ class ChoiceList implements ChoiceListInterface } /** - * 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 +263,7 @@ class ChoiceList implements ChoiceListInterface } /** - * 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) { diff --git a/src/Symfony/Component/Form/Extension/Core/ChoiceList/LazyChoiceList.php b/src/Symfony/Component/Form/Extension/Core/ChoiceList/LazyChoiceList.php index 8a83ec833d..29551de560 100644 --- a/src/Symfony/Component/Form/Extension/Core/ChoiceList/LazyChoiceList.php +++ b/src/Symfony/Component/Form/Extension/Core/ChoiceList/LazyChoiceList.php @@ -32,10 +32,8 @@ abstract class LazyChoiceList implements ChoiceListInterface private $choiceList; /** - * Returns the list of choices - * - * @return array The choices with their indices as keys. - */ + * {@inheritdoc} + */ public function getChoices() { if (!$this->choiceList) { @@ -46,10 +44,8 @@ abstract class LazyChoiceList implements ChoiceListInterface } /** - * Returns the values for the choices - * - * @return array The values with the corresponding choice indices as keys. - */ + * {@inheritdoc} + */ public function getValues() { if (!$this->choiceList) { @@ -60,27 +56,8 @@ abstract class LazyChoiceList implements 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. - */ + * {@inheritdoc} + */ public function getPreferredViews() { if (!$this->choiceList) { @@ -91,29 +68,8 @@ abstract class LazyChoiceList implements 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. - * - * @see getPreferredValues - */ + * {@inheritdoc} + */ public function getRemainingViews() { if (!$this->choiceList) { @@ -124,13 +80,8 @@ abstract class LazyChoiceList implements ChoiceListInterface } /** - * Returns the choices corresponding to the given values. - * - * @param array $values An array of choice values. Not existing values in - * this array are ignored. - * - * @return array An array of choices with ascending, 0-based numeric keys - */ + * {@inheritdoc} + */ public function getChoicesForValues(array $values) { if (!$this->choiceList) { @@ -141,14 +92,8 @@ abstract class LazyChoiceList implements ChoiceListInterface } /** - * Returns the values corresponding to the given choices. - * - * @param array $choices An array of choices. Not existing choices in this - * array are ignored. - * - * @return array An array of choice values with ascending, 0-based numeric - * keys - */ + * {@inheritdoc} + */ public function getValuesForChoices(array $choices) { if (!$this->choiceList) { @@ -159,13 +104,8 @@ abstract class LazyChoiceList implements ChoiceListInterface } /** - * Returns the indices corresponding to the given choices. - * - * @param array $choices An array of choices. Not existing choices in this - * array are ignored. - * - * @return array An array of indices with ascending, 0-based numeric keys - */ + * {@inheritdoc} + */ public function getIndicesForChoices(array $choices) { if (!$this->choiceList) { @@ -176,13 +116,8 @@ abstract class LazyChoiceList implements ChoiceListInterface } /** - * Returns the indices corresponding to the given values. - * - * @param array $values An array of choice values. Not existing values in - * this array are ignored. - * - * @return array An array of indices with ascending, 0-based numeric keys - */ + * {@inheritdoc} + */ public function getIndicesForValues(array $values) { if (!$this->choiceList) { From 57cc5313852ca788e11ae7eb24ffd52e0049c27c Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Mon, 30 Jan 2012 18:39:44 +0100 Subject: [PATCH 6/6] [Form] Improved PHPDocs of choice lists --- .../Extension/Core/ChoiceList/ChoiceList.php | 11 +++++- .../Core/ChoiceList/ObjectChoiceList.php | 12 +++++-- .../Core/ChoiceList/SimpleChoiceList.php | 35 +++++++++++++++++-- 3 files changed, 51 insertions(+), 7 deletions(-) diff --git a/src/Symfony/Component/Form/Extension/Core/ChoiceList/ChoiceList.php b/src/Symfony/Component/Form/Extension/Core/ChoiceList/ChoiceList.php index d38c32bc79..c9d09a4904 100644 --- 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\Exception\InvalidConfigurationException; 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. + * + * + * $choices = array(true, false); + * $labels = array('Agree', 'Disagree'); + * $choiceList = new ChoiceList($choices, $labels); + * * * @author Bernhard Schussek */ diff --git a/src/Symfony/Component/Form/Extension/Core/ChoiceList/ObjectChoiceList.php b/src/Symfony/Component/Form/Extension/Core/ChoiceList/ObjectChoiceList.php index 3533326be1..daf13efcd3 100644 --- a/src/Symfony/Component/Form/Extension/Core/ChoiceList/ObjectChoiceList.php +++ b/src/Symfony/Component/Form/Extension/Core/ChoiceList/ObjectChoiceList.php @@ -17,11 +17,17 @@ use Symfony\Component\Form\Exception\UnexpectedTypeException; use Symfony\Component\Form\Exception\InvalidPropertyException; /** - * A choice list that can store object choices. + * A choice list for object choices. * * Supports generation of choice labels, choice groups, choice values and - * choice indices by introspecting the properties of the object (or - * associated objects). + * choice indices by calling getters of the object (or associated objects). + * + * + * $choices = array($user1, $user2); + * + * // call getName() to determine the choice labels + * $choiceList = new ObjectChoiceList($choices, 'name'); + * * * @author Bernhard Schussek */ diff --git a/src/Symfony/Component/Form/Extension/Core/ChoiceList/SimpleChoiceList.php b/src/Symfony/Component/Form/Extension/Core/ChoiceList/SimpleChoiceList.php index 748f8397c0..27a7382c03 100644 --- a/src/Symfony/Component/Form/Extension/Core/ChoiceList/SimpleChoiceList.php +++ b/src/Symfony/Component/Form/Extension/Core/ChoiceList/SimpleChoiceList.php @@ -15,10 +15,39 @@ namespace Symfony\Component\Form\Extension\Core\ChoiceList; use Symfony\Component\Form\Exception\UnexpectedTypeException; /** - * A choice list that can store any choices that are allowed as PHP array keys. + * A choice list for choices of type string or integer. * - * The value strategy of simple choice lists is fixed to ChoiceList::COPY_CHOICE, - * since array keys are always valid choice values. + * Choices and their associated labels can be passed in a single array. Since + * choices are passed as array keys, only strings or integer choices are + * allowed. + * + * + * $choiceList = new SimpleChoiceList(array( + * 'creditcard' => 'Credit card payment', + * 'cash' => 'Cash payment', + * )); + * + * + * The default value generation strategy is `ChoiceList::COPY_CHOICE`, because + * choice values must be scalar, and the choices passed to this choice list + * are guaranteed to be scalar. + * + * The default index generation strategy is `ChoiceList::GENERATE`, so that + * your choices can also contain values that are illegal as indices. If your + * choices are guaranteed to start with a letter, digit or underscore and only + * contain letters, digits, underscores, hyphens and colons, you can set the + * strategy to `ChoiceList::COPY_CHOICE` instead. + * + * + * $choices = array( + * 'creditcard' => 'Credit card payment', + * 'cash' => 'Cash payment', + * ); + * + * // value generation: COPY_CHOICE (the default) + * // index generation: COPY_CHOICE (custom) + * $choiceList = new SimpleChoiceList($choices, array(), ChoiceList::COPY_CHOICE, ChoiceList::COPY_CHOICE); + * * * @author Bernhard Schussek */