8.5.x NestedArray.php NestedArray::setValue(array &$array, array $parents, $value, $force = FALSE)
8.0.x NestedArray.php NestedArray::setValue(array &$array, array $parents, $value, $force = FALSE)
8.1.x NestedArray.php NestedArray::setValue(array &$array, array $parents, $value, $force = FALSE)
8.2.x NestedArray.php NestedArray::setValue(array &$array, array $parents, $value, $force = FALSE)
8.3.x NestedArray.php NestedArray::setValue(array &$array, array $parents, $value, $force = FALSE)
8.4.x NestedArray.php NestedArray::setValue(array &$array, array $parents, $value, $force = FALSE)
8.6.x NestedArray.php NestedArray::setValue(array &$array, array $parents, $value, $force = FALSE)

Sets 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.


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

// Or, it might be further nested:
$form['signature_settings']['user']['signature'] = array(
  '#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


in the first case or


in the second case.

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

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

Instead, use this helper function:

NestedArray::setValue($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:

$form['signature_settings']['signature'] = $element;


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

array $parents: An array of parent keys, starting with the outermost key.

mixed $value: The value to set.

bool $force: (optional) If TRUE, the value is forced into the structure even if it requires the deletion of an already existing non-array parent value. If FALSE, PHP throws an error if trying to add into a value that is not an array. Defaults to FALSE.

See also



17 calls to NestedArray::setValue()
CommentLinkBuilder::buildCommentedEntityLinks in core/modules/comment/src/CommentLinkBuilder.php
Builds links for the given entity.
EntityConfigBase::updateEntityProperty in core/modules/migrate/src/Plugin/migrate/destination/EntityConfigBase.php
Updates a (possible nested) entity property with a value.
FileWidget::submit in core/modules/file/src/Plugin/Field/FieldWidget/FileWidget.php
Form submission handler for upload/remove button of formElement().
FileWidget::validateMultipleCount in core/modules/file/src/Plugin/Field/FieldWidget/FileWidget.php
Form element validation callback for upload element on file widget. Checks if user has uploaded more files than allowed.
file_managed_file_submit in core/modules/file/file.module
Form submission handler for upload / remove buttons of managed_file elements.

... See full list


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


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




public static function setValue(array &$array, array $parents, $value, $force = FALSE) {
  $ref =& $array;
  foreach ($parents as $parent) {

    // PHP auto-creates container arrays and NULL entries without error if $ref
    // is NULL, but throws an error if $ref is set, but not an array.
    if ($force && isset($ref) && !is_array($ref)) {
      $ref = [];
    $ref =& $ref[$parent];
  $ref = $value;