function form_select_options

Converts the options in a select element into a structured array for output.

This function calls itself recursively to obtain the values for each optgroup within the list of options and when the function encounters an object with an 'options' property inside $element['#options'].

Parameters

array $element: An associative array containing properties of the select element. See \Drupal\Core\Render\Element\Select for details, but note that the #empty_option and #empty_value properties are processed, and the #value property is set, before reaching this function.

array|null $choices: (optional) Either an associative array of options in the same format as $element['#options'] above, or NULL. This parameter is only used internally and is not intended to be passed in to the initial function call.

Return value

mixed[] A structured, possibly nested, array of options and optgroups for use in a select form element.

• label: A translated string whose value is the text of a single HTML option element, or the label attribute for an optgroup.
• options: Optional, array of options for an optgroup.
• selected: A boolean that indicates whether the option is selected when rendered.
• type: A string that defines the element type. The value can be 'option' or 'optgroup'.
• value: A string that contains the value attribute for the option.

File

core/includes/form.inc, line 69

Code

function form_select_options($element, $choices = NULL) {
    if (!isset($choices)) {
        if (empty($element['#options'])) {
            return [];
        }
        $choices = $element['#options'];
        $sort_options = isset($element['#sort_options']) && $element['#sort_options'];
        $sort_start = $element['#sort_start'] ?? 0;
    }
    else {
        // We are within an option group.
        $sort_options = isset($choices['#sort_options']) && $choices['#sort_options'];
        $sort_start = $choices['#sort_start'] ?? 0;
        unset($choices['#sort_options']);
        unset($choices['#sort_start']);
    }
    // array_key_exists() accommodates the rare event where $element['#value'] is NULL.
    // isset() fails in this situation.
    $value_valid = isset($element['#value']) || array_key_exists('#value', $element);
    $value_is_array = $value_valid && is_array($element['#value']);
    // Check if the element is multiple select and no value has been selected.
    $empty_value = empty($element['#value']) && !empty($element['#multiple']);
    $options = [];
    foreach ($choices as $key => $choice) {
        if (is_array($choice)) {
            $options[] = [
                'type' => 'optgroup',
                'label' => $key,
                'options' => form_select_options($element, $choice),
            ];
        }
        elseif (is_object($choice) && isset($choice->option)) {
            $options = array_merge($options, form_select_options($element, $choice->option));
        }
        else {
            $option = [];
            $key = (string) $key;
            $empty_choice = $empty_value && $key == '_none';
            if ($value_valid && (!$value_is_array && (string) $element['#value'] === $key || $value_is_array && in_array($key, $element['#value']) || $empty_choice)) {
                $option['selected'] = TRUE;
            }
            else {
                $option['selected'] = FALSE;
            }
            $option['type'] = 'option';
            $option['value'] = $key;
            $option['label'] = $choice;
            $options[] = $option;
        }
    }
    if ($sort_options) {
        $unsorted = array_slice($options, 0, $sort_start);
        $sorted = array_slice($options, $sort_start);
        uasort($sorted, function ($a, $b) {
            return strcmp((string) $a['label'], (string) $b['label']);
        });
        $options = array_merge($unsorted, $sorted);
    }
    return $options;
}