class SimpleChoiceList extends ChoiceList

deprecated since version 2.7, to be removed in 3.0. Use {@link \Symfony\Component\Form\ChoiceList\ArrayChoiceList} instead.

A choice list for choices of type string or integer.

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. Choices may also be given as hierarchy of unlimited depth by creating nested arrays. The title of the sub-hierarchy can be stored in the array key pointing to the nested array.

$choiceList = new SimpleChoiceList(array(
    'creditcard' => 'Credit card payment',
    'cash' => 'Cash payment',
));

Properties

protected $choices The choices with their indices as keys. from ChoiceList
protected $values The choice values with the indices of the matching choices as keys. from ChoiceList

Methods

__construct(array|Traversable $choices, array $preferredChoices = array())

Creates a new simple choice list.

initialize(array|Traversable $choices, array $labels, array $preferredChoices)

Initializes the list with choices.

array
getChoices()

Returns the list of choices.

array
getValues()

Returns the values for the choices.

array
getPreferredViews()

Returns the choice views of the preferred choices as nested array with the choice groups as top-level keys.

array
getRemainingViews()

Returns the choice views of the choices that are not preferred as nested array with the choice groups as top-level keys.

array
getChoicesForValues(array $values)

Returns the choices corresponding to the given values.

array
getValuesForChoices(array $choices)

Returns the values corresponding to the given choices.

array
getIndicesForChoices(array $choices) deprecated

Returns the indices corresponding to the given choices.

array
getIndicesForValues(array $values) deprecated

Returns the indices corresponding to the given values.

addChoices(array $bucketForPreferred, array $bucketForRemaining, array|Traversable $choices, array $labels, array $preferredChoices)

Recursively adds the given choices to the list.

addChoiceGroup(string $group, array $bucketForPreferred, array $bucketForRemaining, array $choices, array $labels, array $preferredChoices)

Recursively adds a choice group.

addChoice(array $bucketForPreferred, array $bucketForRemaining, mixed $choice, string $label, array $preferredChoices)

Adds a new choice.

bool
isPreferred(mixed $choice, array $preferredChoices)

Returns whether the given choice should be preferred judging by the given array of preferred choices.

int|string
createIndex(mixed $choice)

Creates a new unique index for this choice.

string
createValue(mixed $choice)

Creates a new unique value for this choice.

string
fixValue(mixed $value)

Fixes the data type of the given choice value to avoid comparison problems.

array
fixValues(array $values)

Fixes the data types of the given choice values to avoid comparison problems.

int|string
fixIndex(mixed $index)

Fixes the data type of the given choice index to avoid comparison problems.

array
fixIndices(array $indices)

Fixes the data types of the given choice indices to avoid comparison problems.

mixed
fixChoice(mixed $choice)

Converts the choice to a valid PHP array key.

array
fixChoices(array $choices)

Fixes the data type of the given choices to avoid comparison problems.

Details

at line 48
__construct(array|Traversable $choices, array $preferredChoices = array())

Creates a new simple choice list.

Parameters

array|Traversable $choices The array of choices. Choices may also be given as hierarchy of unlimited depth. Hierarchies are created by creating nested arrays. The title of the sub-hierarchy can be stored in the array key pointing to the nested array. The topmost level of the hierarchy may also be a \Traversable.
array $preferredChoices A flat array of choices that should be presented to the user with priority

in ChoiceList at line 98
protected initialize(array|Traversable $choices, array $labels, array $preferredChoices)

Initializes the list with choices.

Safe to be called multiple times. The list is cleared on every call.

Parameters

array|Traversable $choices The choices to write into the list
array $labels The labels belonging to the choices
array $preferredChoices The choices to display with priority

in ChoiceList at line 117
array getChoices()

Returns the list of choices.

Return Value

array The choices with their indices as keys

in ChoiceList at line 125
array getValues()

Returns the values for the choices.

Return Value

array The values with the corresponding choice indices as keys

in ChoiceList at line 133
array getPreferredViews()

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 Value

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

in ChoiceList at line 141
array getRemainingViews()

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 Value

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

at line 57
array getChoicesForValues(array $values)

Returns the choices corresponding to the given values.

The choices can have any data type.

The choices must be returned with the same keys and in the same order as the corresponding values in the given array.

Parameters

array $values An array of choice values. Not existing values in this array are ignored

Return Value

array An array of choices with ascending, 0-based numeric keys

at line 69
array getValuesForChoices(array $choices)

Returns the values corresponding to the given choices.

The values must be strings.

The values must be returned with the same keys and in the same order as the corresponding choices in the given array.

Parameters

array $choices An array of choices. Not existing choices in this array are ignored

Return Value

array An array of choice values with ascending, 0-based numeric keys

in ChoiceList at line 199
array getIndicesForChoices(array $choices) deprecated

deprecated since version 2.4, to be removed in 3.0.

Returns the indices corresponding to the given choices.

The indices must be positive integers or strings accepted by {@link \Symfony\Component\Form\FormConfigBuilder::validateName()}.

The index "placeholder" is internally reserved.

The indices must be returned with the same keys and in the same order as the corresponding choices in the given array.

Parameters

array $choices An array of choices. Not existing choices in this array are ignored

Return Value

array An array of indices with ascending, 0-based numeric keys

in ChoiceList at line 227
array getIndicesForValues(array $values) deprecated

deprecated since version 2.4, to be removed in 3.0.

Returns the indices corresponding to the given values.

The indices must be positive integers or strings accepted by {@link \Symfony\Component\Form\FormConfigBuilder::validateName()}.

The index "placeholder" is internally reserved.

The indices must be returned with the same keys and in the same order as the corresponding values in the given array.

Parameters

array $values An array of choice values. Not existing values in this array are ignored

Return Value

array An array of indices with ascending, 0-based numeric keys

at line 90
protected addChoices(array $bucketForPreferred, array $bucketForRemaining, array|Traversable $choices, array $labels, array $preferredChoices)

Recursively adds the given choices to the list.

Takes care of splitting the single $choices array passed in the constructor into choices and labels.

Parameters

array $bucketForPreferred The bucket where to store the preferred view objects
array $bucketForRemaining The bucket where to store the non-preferred view objects
array|Traversable $choices The list of choices
array $labels The labels corresponding to the choices
array $preferredChoices The preferred choices

in ChoiceList at line 306
protected addChoiceGroup(string $group, array $bucketForPreferred, array $bucketForRemaining, array $choices, array $labels, array $preferredChoices)

Recursively adds a choice group.

Parameters

string $group The name of the group
array $bucketForPreferred The bucket where to store the preferred view objects
array $bucketForRemaining The bucket where to store the non-preferred view objects
array $choices The list of choices in the group
array $labels The labels corresponding to the choices in the group
array $preferredChoices The preferred choices

Exceptions

InvalidConfigurationException if no valid value or index could be created for a choice

in ChoiceList at line 341
protected addChoice(array $bucketForPreferred, array $bucketForRemaining, mixed $choice, string $label, array $preferredChoices)

Adds a new choice.

Parameters

array $bucketForPreferred The bucket where to store the preferred view objects
array $bucketForRemaining The bucket where to store the non-preferred view objects
mixed $choice The choice to add
string $label The label for the choice
array $preferredChoices The preferred choices

Exceptions

InvalidConfigurationException if no valid value or index could be created

at line 130
protected bool isPreferred(mixed $choice, array $preferredChoices)

Returns whether the given choice should be preferred judging by the given array of preferred choices.

Optimized for performance by treating the preferred choices as array where choices are stored in the keys.

Parameters

mixed $choice The choice to test
array $preferredChoices An array of preferred choices

Return Value

bool Whether the choice is preferred

in ChoiceList at line 394
protected int|string createIndex(mixed $choice)

Creates a new unique index for this choice.

Extension point to change the indexing strategy.

Parameters

mixed $choice The choice to create an index for

Return Value

int|string a unique index containing only ASCII letters, digits and underscores

at line 159
protected string createValue(mixed $choice)

Creates a new unique value for this choice.

By default, an integer is generated since it cannot be guaranteed that all values in the list are convertible to (unique) strings. Subclasses can override this behaviour if they can guarantee this property.

Parameters

mixed $choice The choice to create a value for

Return Value

string A unique string

in ChoiceList at line 423
protected string fixValue(mixed $value)

Fixes the data type of the given choice value to avoid comparison problems.

Parameters

mixed $value The choice value

Return Value

string The value as string

in ChoiceList at line 436
protected array fixValues(array $values)

Fixes the data types of the given choice values to avoid comparison problems.

Parameters

array $values The choice values

Return Value

array The values as strings

in ChoiceList at line 453
protected int|string fixIndex(mixed $index)

Fixes the data type of the given choice index to avoid comparison problems.

Parameters

mixed $index The choice index

Return Value

int|string The index as PHP array key

in ChoiceList at line 470
protected array fixIndices(array $indices)

Fixes the data types of the given choice indices to avoid comparison problems.

Parameters

array $indices The choice indices

Return Value

array The indices as strings

at line 143
protected mixed fixChoice(mixed $choice)

Converts the choice to a valid PHP array key.

Parameters

mixed $choice The choice

Return Value

mixed The fixed choice

at line 151
protected array fixChoices(array $choices)

Fixes the data type of the given choices to avoid comparison problems.

Parameters

array $choices The choices

Return Value

array The fixed choices