Skip to content

Commit b9162e8

Browse files
author
Jules Pietri
committed
[Form] Fixed some phpdocs
1 parent b43cfc8 commit b9162e8

File tree

4 files changed

+42
-20
lines changed

4 files changed

+42
-20
lines changed

‎src/Symfony/Component/Form/ChoiceList/ArrayChoiceList.php

Lines changed: 7 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,10 @@
1515
* A list of choices with arbitrary data types.
1616
*
1717
* The user of this class is responsible for assigning string values to the
18-
* choices. Both the choices and their values are passed to the constructor.
19-
* Each choice must have a corresponding value (with the same array key) in
20-
* the value array.
18+
* choices annd for their uniqueness.
19+
* Both the choices and their values are passed to the constructor.
20+
* Each choice must have a corresponding value (with the same key) in
21+
* the values array.
2122
*
2223
* @author Bernhard Schussek <bschussek@gmail.com>
2324
*/
@@ -43,12 +44,6 @@ class ArrayChoiceList implements ChoiceListInterface
4344
* @var int[]|string[]
4445
*/
4546
protected $originalKeys;
46-
47-
/**
48-
* The callback for creating the value for a choice.
49-
*
50-
* @var callable
51-
*/
5247
protected $valueCallback;
5348

5449
/**
@@ -212,6 +207,8 @@ protected function flatten(array $choices, $value, &$choicesByValues, &$keysByVa
212207
/**
213208
* Checks whether the given choices can be cast to strings without
214209
* generating duplicates.
210+
* This method is responsible for preventing conflict between scalar values
211+
* and the empty value.
215212
*
216213
* @param array $choices The choices
217214
* @param array|null $cache The cache for previously checked entries. Internal
@@ -232,6 +229,7 @@ private function castableToString(array $choices, array &$cache = [])
232229
return false;
233230
}
234231

232+
// prevent having false casted to the empty string by isset()
235233
$choice = false === $choice ? '0' : (string) $choice;
236234

237235
if (isset($cache[$choice])) {

‎src/Symfony/Component/Form/ChoiceList/ChoiceListInterface.php

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,25 @@ public function getChoices();
3535
/**
3636
* Returns the values for the choices.
3737
*
38-
* The values are strings that do not contain duplicates.
38+
* The values are strings that do not contain duplicates:
39+
*
40+
* $form->add('field', 'choice', [
41+
* 'choices' => [
42+
* 'Decided' => ['Yes' => true, 'No' => false],
43+
* 'Undecided' => ['Maybe' => null],
44+
* ],
45+
* ]);
46+
*
47+
* In this example, the result of this method is:
48+
*
49+
* [
50+
* 'Yes' => '0',
51+
* 'No' => '1',
52+
* 'Maybe' => '2',
53+
* ]
54+
*
55+
* Null and false MUST NOT conflict when being casted to string.
56+
* For this some default incremented values SHOULD be computed.
3957
*
4058
* @return string[] The choice values
4159
*/
@@ -62,6 +80,12 @@ public function getValues();
6280
* 'Undecided' => ['Maybe' => '2'],
6381
* ]
6482
*
83+
* Nested arrays do not make sense in a view format unless
84+
* they are used as a convenient way of grouping.
85+
* If the implementation does not intend to support grouped choices,
86+
* this method SHOULD be equivalent to {@link getValues()}.
87+
* The $groupBy callback parameter SHOULD be used instead.
88+
*
6589
* @return string[] The choice values
6690
*/
6791
public function getStructuredValues();

‎src/Symfony/Component/Form/ChoiceList/Factory/ChoiceListFactoryInterface.php

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,8 @@ interface ChoiceListFactoryInterface
2828
* The choices should be passed in the values of the choices array.
2929
*
3030
* Optionally, a callable can be passed for generating the choice values.
31-
* The callable receives the choice as first and the array key as the second
32-
* argument.
31+
* The callable receives the choice as only argument.
32+
* Null may be passed when the choice list contains the empty value.
3333
*
3434
* @param iterable $choices The choices
3535
* @param callable|null $value The callable generating the choice
@@ -43,8 +43,8 @@ public function createListFromChoices($choices, $value = null);
4343
* Creates a choice list that is loaded with the given loader.
4444
*
4545
* Optionally, a callable can be passed for generating the choice values.
46-
* The callable receives the choice as first and the array key as the second
47-
* argument.
46+
* The callable receives the choice as only argument.
47+
* Null may be passed when the choice list contains the empty value.
4848
*
4949
* @param ChoiceLoaderInterface $loader The choice loader
5050
* @param callable|null $value The callable generating the choice

‎src/Symfony/Component/Form/ChoiceList/Loader/ChoiceLoaderInterface.php

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,8 @@ interface ChoiceLoaderInterface
2828
* Loads a list of choices.
2929
*
3030
* Optionally, a callable can be passed for generating the choice values.
31-
* The callable receives the choice as first and the array key as the second
32-
* argument.
31+
* The callable receives the choice as only argument.
32+
* Null may be passed when the choice list contains the empty value.
3333
*
3434
* @param callable|null $value The callable which generates the values
3535
* from choices
@@ -45,8 +45,8 @@ public function loadChoiceList($value = null);
4545
* corresponding values in the given array.
4646
*
4747
* Optionally, a callable can be passed for generating the choice values.
48-
* The callable receives the choice as first and the array key as the second
49-
* argument.
48+
* The callable receives the choice as only argument.
49+
* Null may be passed when the choice list contains the empty value.
5050
*
5151
* @param string[] $values An array of choice values. Non-existing
5252
* values in this array are ignored
@@ -63,8 +63,8 @@ public function loadChoicesForValues(array $values, $value = null);
6363
* corresponding choices in the given array.
6464
*
6565
* Optionally, a callable can be passed for generating the choice values.
66-
* The callable receives the choice as first and the array key as the second
67-
* argument.
66+
* The callable receives the choice as only argument.
67+
* Null may be passed when the choice list contains the empty value.
6868
*
6969
* @param array $choices An array of choices. Non-existing choices in
7070
* this array are ignored

0 commit comments

Comments
 (0)