function form_get_options

Returns the indexes of a select element's options matching a given key.

This function is useful if you need to modify the options that are already in a form element; for example, to remove choices which are not valid because of additional filters imposed by another module. One example might be altering the choices in a taxonomy selector. To correctly handle the case of a multiple hierarchy taxonomy, #options arrays can now hold an array of objects, instead of a direct mapping of keys to labels, so that multiple choices in the selector can have the same key (and label). This makes it difficult to manipulate directly, which is why this helper function exists.

This function does not support optgroups (when the elements of the #options array are themselves arrays), and will return FALSE if arrays are found. The caller must either flatten/restore or manually do their manipulations in this case, since returning the index is not sufficient, and supporting this would make the "helper" too complicated and cumbersome to be of any help.

As usual with functions that can return [] or FALSE, do not forget to use === and !== if needed.

Parameters

$element: The select element to search.

$key: The key to look for.

Return value

array|bool An array of indexes that match the given $key. Array will be empty if no elements were found. FALSE if optgroups were found.

File

core/includes/form.inc, line 165

Code

function form_get_options($element, $key) {
    $keys = [];
    foreach ($element['#options'] as $index => $choice) {
        if (is_array($choice)) {
            return FALSE;
        }
        elseif (is_object($choice)) {
            if (isset($choice->option[$key])) {
                $keys[] = $index;
            }
        }
        elseif ($index == $key) {
            $keys[] = $index;
        }
    }
    return $keys;
}