Same name in other branches

1. 9 core/lib/Drupal/Component/Utility/NestedArray.php \Drupal\Component\Utility\NestedArray::unsetValue()
2. 8.9.x core/lib/Drupal/Component/Utility/NestedArray.php \Drupal\Component\Utility\NestedArray::unsetValue()
3. 10 core/lib/Drupal/Component/Utility/NestedArray.php \Drupal\Component\Utility\NestedArray::unsetValue()

Unsets a value in a nested array with variable depth.

This helper function should be used when the depth of the array element you are changing may vary (that is, the number of parent keys is variable). It is primarily used for form structures and renderable arrays.

Example:

// Assume you have a 'signature' element somewhere in a form. It might be:
$form['signature_settings']['signature'] = [
    '#type' => 'text_format',
    '#title' => t('Signature'),
];
// Or, it might be further nested:
$form['signature_settings']['user']['signature'] = [
    '#type' => 'text_format',
    '#title' => t('Signature'),
];

To deal with the situation, the code needs to figure out the route to the element, given an array of parents that is either

[
    'signature_settings',
    'signature',
];

in the first case or

[
    'signature_settings',
    'user',
    'signature',
];

in the second case.

Without this helper function the only way to unset the signature element in one line would be using eval(), which should be avoided:

// Do not do this! Avoid eval().
eval('unset($form[\'' . implode("']['", $parents) . '\']);');

Instead, use this helper function:

NestedArray::unsetValue($form, $parents, $element);

However if the number of array parent keys is static, the value should always be set directly rather than calling this function. For instance, for the first example we could just do:

unset($form['signature_settings']['signature']);

Parameters

array $array: A reference to the array to modify.

array $parents: An array of parent keys, starting with the outermost key and including the key to be unset.

bool $key_existed: (optional) If given, an already defined variable that is altered by reference.

See also

NestedArray::setValue()

NestedArray::getValue()

6 calls to NestedArray::unsetValue()

ConfigBase::clear in core/lib/Drupal/Core/Config/ConfigBase.php

Unsets a value in this configuration object.

FormStateValuesTrait::unsetValue in core/lib/Drupal/Core/Form/FormStateValuesTrait.php

Implements \Drupal\Core\Form\FormStateInterface::unsetValue()

LibraryDiscoveryParser::setOverrideValue in core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php

Overrides the specified library asset.

ListItemBase::deleteSubmit in core/modules/options/src/Plugin/Field/FieldType/ListItemBase.php

Deletes a row/option.

NestedArrayTest::testUnsetValue in core/tests/Drupal/Tests/Component/Utility/NestedArrayTest.php

Tests unsetting nested array values.

... See full list

File

core/lib/Drupal/Component/Utility/NestedArray.php, line 222

Class

NestedArray

Provides helpers to perform operations on nested arrays and array keys of variable depth.

Namespace

Drupal\Component\Utility

Code

public static function unsetValue(array &$array, array $parents, &$key_existed = NULL) {
    $unset_key = array_pop($parents);
    $ref =& self::getValue($array, $parents, $key_existed);
    if ($key_existed && is_array($ref) && \array_key_exists($unset_key, $ref)) {
        $key_existed = TRUE;
        unset($ref[$unset_key]);
    }
    else {
        $key_existed = FALSE;
    }
}

---