From b9162e8cfb625a152ff46ecbdacdb3160f30dd80 Mon Sep 17 00:00:00 2001 From: Jules Pietri Date: Tue, 12 Mar 2019 12:31:54 +0100 Subject: [PATCH] [Form] Fixed some phpdocs --- .../Form/ChoiceList/ArrayChoiceList.php | 16 +++++------- .../Form/ChoiceList/ChoiceListInterface.php | 26 ++++++++++++++++++- .../Factory/ChoiceListFactoryInterface.php | 8 +++--- .../Loader/ChoiceLoaderInterface.php | 12 ++++----- 4 files changed, 42 insertions(+), 20 deletions(-) diff --git a/src/Symfony/Component/Form/ChoiceList/ArrayChoiceList.php b/src/Symfony/Component/Form/ChoiceList/ArrayChoiceList.php index 02685a2504..e7ebc7200b 100644 --- a/src/Symfony/Component/Form/ChoiceList/ArrayChoiceList.php +++ b/src/Symfony/Component/Form/ChoiceList/ArrayChoiceList.php @@ -15,9 +15,10 @@ namespace Symfony\Component\Form\ChoiceList; * A list of choices with arbitrary data types. * * The user of this class is responsible for assigning string values to the - * choices. Both the choices and their values are passed to the constructor. - * Each choice must have a corresponding value (with the same array key) in - * the value array. + * choices annd for their uniqueness. + * Both the choices and their values are passed to the constructor. + * Each choice must have a corresponding value (with the same key) in + * the values array. * * @author Bernhard Schussek */ @@ -43,12 +44,6 @@ class ArrayChoiceList implements ChoiceListInterface * @var int[]|string[] */ protected $originalKeys; - - /** - * The callback for creating the value for a choice. - * - * @var callable - */ protected $valueCallback; /** @@ -212,6 +207,8 @@ class ArrayChoiceList implements ChoiceListInterface /** * Checks whether the given choices can be cast to strings without * generating duplicates. + * This method is responsible for preventing conflict between scalar values + * and the empty value. * * @param array $choices The choices * @param array|null $cache The cache for previously checked entries. Internal @@ -232,6 +229,7 @@ class ArrayChoiceList implements ChoiceListInterface return false; } + // prevent having false casted to the empty string by isset() $choice = false === $choice ? '0' : (string) $choice; if (isset($cache[$choice])) { diff --git a/src/Symfony/Component/Form/ChoiceList/ChoiceListInterface.php b/src/Symfony/Component/Form/ChoiceList/ChoiceListInterface.php index c1d643ee73..9435309dd5 100644 --- a/src/Symfony/Component/Form/ChoiceList/ChoiceListInterface.php +++ b/src/Symfony/Component/Form/ChoiceList/ChoiceListInterface.php @@ -35,7 +35,25 @@ interface ChoiceListInterface /** * Returns the values for the choices. * - * The values are strings that do not contain duplicates. + * The values are strings that do not contain duplicates: + * + * $form->add('field', 'choice', [ + * 'choices' => [ + * 'Decided' => ['Yes' => true, 'No' => false], + * 'Undecided' => ['Maybe' => null], + * ], + * ]); + * + * In this example, the result of this method is: + * + * [ + * 'Yes' => '0', + * 'No' => '1', + * 'Maybe' => '2', + * ] + * + * Null and false MUST NOT conflict when being casted to string. + * For this some default incremented values SHOULD be computed. * * @return string[] The choice values */ @@ -62,6 +80,12 @@ interface ChoiceListInterface * 'Undecided' => ['Maybe' => '2'], * ] * + * Nested arrays do not make sense in a view format unless + * they are used as a convenient way of grouping. + * If the implementation does not intend to support grouped choices, + * this method SHOULD be equivalent to {@link getValues()}. + * The $groupBy callback parameter SHOULD be used instead. + * * @return string[] The choice values */ public function getStructuredValues(); diff --git a/src/Symfony/Component/Form/ChoiceList/Factory/ChoiceListFactoryInterface.php b/src/Symfony/Component/Form/ChoiceList/Factory/ChoiceListFactoryInterface.php index dea2165ec7..41a22586cc 100644 --- a/src/Symfony/Component/Form/ChoiceList/Factory/ChoiceListFactoryInterface.php +++ b/src/Symfony/Component/Form/ChoiceList/Factory/ChoiceListFactoryInterface.php @@ -28,8 +28,8 @@ interface ChoiceListFactoryInterface * The choices should be passed in the values of the choices array. * * Optionally, a callable can be passed for generating the choice values. - * The callable receives the choice as first and the array key as the second - * argument. + * The callable receives the choice as only argument. + * Null may be passed when the choice list contains the empty value. * * @param iterable $choices The choices * @param callable|null $value The callable generating the choice @@ -43,8 +43,8 @@ interface ChoiceListFactoryInterface * Creates a choice list that is loaded with the given loader. * * Optionally, a callable can be passed for generating the choice values. - * The callable receives the choice as first and the array key as the second - * argument. + * The callable receives the choice as only argument. + * Null may be passed when the choice list contains the empty value. * * @param ChoiceLoaderInterface $loader The choice loader * @param callable|null $value The callable generating the choice diff --git a/src/Symfony/Component/Form/ChoiceList/Loader/ChoiceLoaderInterface.php b/src/Symfony/Component/Form/ChoiceList/Loader/ChoiceLoaderInterface.php index 63e5f65210..31d47d539c 100644 --- a/src/Symfony/Component/Form/ChoiceList/Loader/ChoiceLoaderInterface.php +++ b/src/Symfony/Component/Form/ChoiceList/Loader/ChoiceLoaderInterface.php @@ -28,8 +28,8 @@ interface ChoiceLoaderInterface * Loads a list of choices. * * Optionally, a callable can be passed for generating the choice values. - * The callable receives the choice as first and the array key as the second - * argument. + * The callable receives the choice as only argument. + * Null may be passed when the choice list contains the empty value. * * @param callable|null $value The callable which generates the values * from choices @@ -45,8 +45,8 @@ interface ChoiceLoaderInterface * corresponding values in the given array. * * Optionally, a callable can be passed for generating the choice values. - * The callable receives the choice as first and the array key as the second - * argument. + * The callable receives the choice as only argument. + * Null may be passed when the choice list contains the empty value. * * @param string[] $values An array of choice values. Non-existing * values in this array are ignored @@ -63,8 +63,8 @@ interface ChoiceLoaderInterface * corresponding choices in the given array. * * Optionally, a callable can be passed for generating the choice values. - * The callable receives the choice as first and the array key as the second - * argument. + * The callable receives the choice as only argument. + * Null may be passed when the choice list contains the empty value. * * @param array $choices An array of choices. Non-existing choices in * this array are ignored