Add helper methods to inject items into a particular position in associative arrays

Seems like this would be useful for core. I'm no array expert but it looks good.

The functin may be useful.

But, I think you are better off with a combination of array_keys, array_search and array_splice. timer it out.

array_splice() removes the elements designated by offset and length from the input array, and replaces them with the elements of the replacement array, if supplied. It returns an array containing the extracted elements. Note that numeric keys in input are not preserved.

sorry for not reading the manual page before :( but losing numberic keys is not good :( array_slice also resets numeric keys :(

i wrote a different version for my big nodeapi submit handler patch. since that patch is dormant for now, i think this function should be considered for core under this issue. my version is very small.

Aren't weights supposed to let us put things where we want?

there are no weights in submit/validate handlers, for example.

Nor in form_alter for most forms. For example, I was trying tonight to alter taxonomy_image so that the form would appear in the actual taxomomy edit page rather than on a separate tab. At the time the form is built, none of the fields are assigned weights, therefore the additions always appear /below/ the Submit/Delete buttons which is less than ideal.

However, this function didn't allow me to do that either. :P

function taxonomy_image_form_alter($form_id, &$original_form) {

  if ($form_id == 'taxonomy_form_term') {

    // $form definition...

    $original_form = drupal_array_insert($original_form, 'submit', $form, TRUE);
    return $original_form;

  }
}

// still appears under the Submit/Delete buttons. ;(

...either that or I'm just tired and being stupid, which is also very likely. ;) I just figured I'd mention it here since this function sounds like it should allow me to do that.

@webchick - in your example you are accepting $original_form as a reference AND returning it. not good, though i dunno if thats bad enough to explain the failure. anyone available to review this some more?

there is now a #weight element...

huh? we have had #weight since fapi was born. how does that help with the stated problem?

Feature requests go to 7.x-dev.

I had a need for this functionality so did some testing on the two patches ... I was able to get what I wanted by using jjeff's version in comment 3 ... the following "code" is probably lengthier than it needs to be, but it illustrates that the function performs as promised. I was not able to get this functionality from moshe's patch as they indeed have different purposes.

// text keys
$before_submit = drupal_array_insert($form, '#submit', array('mykey' => 'test'), TRUE );

[mykey] => test
[#submit] => Array
 (
  [0] => user_register_submit
)


$after_submit = drupal_array_insert($form, '#submit', array('mykey' => 'test'), FALSE ); 

[#submit] => Array
 (
  [0] => user_register_submit
 )
[mykey] => test


//numeric keys
$before_submit = drupal_array_insert($form, '#submit', array('test'), TRUE );

[0] => test
[#submit] => Array
 (
  [0] => user_register_submit
 )


$after_submit = drupal_array_insert($form, '#submit', array('test'), FALSE );

[#submit] => Array
 (
  [0] => user_register_submit
 )
[0] => test

// text keys
$before_submit = drupal_array_insert($form['#submit'], 0, array('mykey' => 'test'), TRUE );

Array
(
 [mykey] => test
 [0] => user_register_submit
)


$after_submit = drupal_array_insert($form['#submit'], 0, array('mykey' => 'test'), FALSE ); 

Array
(
 [0] => user_register_submit
 [mykey] => test
)

//numeric keys
$before_submit = drupal_array_insert($form['#submit'], 0, array('test'), TRUE );

Array
(
 [0] => test
 [1] => user_register_submit
)



$after_submit = drupal_array_insert($form['#submit'], 0, array('test'), FALSE );

Array
(
 [0] => user_register_submit
 [1] => test
)

Just for kicks I tried to break the above tests by setting the key of the array I was passing in to the same as the key I was trying to position before and after. This worked as promised with numbers. When I tried conflicting string keys like in the following it simply returned the original value of $form

$before_submit = drupal_array_insert($form, '#submit', array('#submit' => 'test'), TRUE );

Hope that helps

This is great! I did a google search for this functionality and the Drupal page was the first hit :).

#3 works as expected for me, and helps in the use case where no weights are assigned to elements. I'll plan on writing a patch + test for this soon.

D8 material. What I'd really like to see in D8 is full DOM-like management of form/render arrays, perhaps modeled after jQuery, if we're able to do so in a performant way.

One of Steven's masterpieces - http://drupal.org/project/fquery. He didn't ever maintain it so it has not seen any traction. But someone should really dust it off and promote.

subscribing from #692950: Use hook_module_implements_alter to allow modules to alter the weight of hooks in module_implements.

I'd like to see moshe's patch in #5 make it in. It's short and extremely useful when altering forms. For example, to insert a new column in a tableselect or table, you need to insert a new entry into $element['#header']

Subscribing...

Resurrecting this issue. '#weight' can solve many, but not all, reasons for this helper function. In addition to one use in batch_set() there are certainly some additional uses in contrib. For example, CAS uses this technique to add a column to a table render array. [Clearly this is something '#weight' would never be used for].

+++ b/core/includes/common.inc
@@ -2602,6 +2602,26 @@ function drupal_exit($destination = NULL) {
+ * @param $position
+ *   The position in $array before which $insert_array is to be inserted.

If you have to give a numeric position for the insertion, then I don't really see the point of it. You're only saving a couple of lines in cases where you know the position already.

The OP function was useful because you often *don't* know the position of the array where you want to insert something, you know it's 'after key 'foo'' or 'before key 'bar'.

Here's the OP's function tweaked for current coding standards and modified to change the given array directly, which keeps it in line with array_splice().

/**
 * Inserts values into an array after a given key.
 *
 * Values from $insert_array are inserted after (or before) $key in $array. If
 * $key is not found, $insert_array is appended to $array using array_merge().
 *
 * @param $array
 *   The array to insert into. Passed by reference and altered in place.
 * @param $key
 *   The key of $array to insert after
 * @param $insert_array
 *   An array whose values should be inserted.
 * @param $before
 *   If TRUE, insert before the given key, rather than after it.
 *   Defaults to inserting after.
 */
function array_insert(&$array, $key, $insert_array, $before = FALSE) {
  $done = FALSE;
  foreach ($array as $array_key => $array_val) {
    if (!$before) {
      $new_array[$array_key] = $array_val;
    }
    if ($array_key == $key && !$done) {
      foreach ($insert_array as $insert_array_key => $insert_array_val) {
        $new_array[$insert_array_key] = $insert_array_val;
      }
      $done = TRUE;
    }
    if ($before) {
      $new_array[$array_key] = $array_val;
    }
  }
  if (!$done) {
    $new_array = array_merge($array, $insert_array);
  }
  // Put the new array in the place of the original.
  $array = $new_array;
}

Could do with some more comments to explain how it works, though I haven't fully worked that out yet.... it does work though :D

#15: +1! I googled and grabbed #23. Saved me a lot of work turning dealing with steps in a D7 install profile into one liners!

If it is backport elegible (not sure) or considering backports module, wanted to add my use case. Subscribing.

Tagging

Nice. Tis lets me really inject additional views fileds and filters into a specific place with a view:

/**
 * Implements hook_views_default_view_alter().
 */
function mymodule_locale_views_default_views_alter(&$views) {
  if (isset($views['admin_views_node'])) {
    $handler =& $views['admin_views_node']->display['default']->handler;

    /* Field: Content: Language */
    $language_field = array();
    $language_field['language']['id'] = 'language';
    $language_field['language']['table'] = 'node';
    $language_field['language']['field'] = 'language';
    $language_field['language']['empty'] = ' - ';
    array_insert(&$handler->display->display_options['fields'], 'name', $language_field);

    /* Filter criterion: Content: Language */
    $language_filter = array();
    $language_filter['language']['id'] = 'language';
    $language_filter['language']['table'] = 'node';
    $language_filter['language']['field'] = 'language';
    $language_filter['language']['value'] = array(
      'und' => 'und',
      'ie' => 'ie',
      'en' => 'en',
    );
    $language_filter['language']['group'] = 1;
    $language_filter['language']['exposed'] = TRUE;
    $language_filter['language']['expose']['operator_id'] = 'language_op';
    $language_filter['language']['expose']['label'] = 'Language';
    $language_filter['language']['expose']['operator'] = 'language_op';
    $language_filter['language']['expose']['identifier'] = 'language';
    $language_filter['language']['expose']['reduce'] = TRUE;
    array_insert(&$handler->display->display_options['filters'], 'uid', $language_filter);
  }
}

This should be rewritten as a method like in #1705920: Convert all calls to procedural drupal_array_*() functions to Drupal\Component\Utility\NestedArray, once that's in.

Ah ha! Setting my issue/patch as duplicate of this: #1343024: Add drupal_array_insert_before() & drupal_array_insert_after()

For those who need it today, here is a patch for 7.15 based on #23 (Thanks a lot !)

For consistency reasons, I changed function signature to

drupal_array_insert(&$array, $key, $insert_array, $before = FALSE)

Is core going to use that, or is it just a utility function to help contrib module for _alter()?

A long time ago in #21 there were some proposed uses in core. Not sure if those are still relevant.

Tagging

As per #27, rerolling joachim's code (#21) and moving from postponed to active again.

#47: drupal--66183--array_insert-47.patch queued for re-testing.

Is there any place where we can take advantage of this? With the introduction of form controllers, I see the need for this slowly fade.

Not only forms were intended to benefit from this. IMO, it's a useful function to have for dealing with arrays.
My use case was inserting a step in an install profile. I'm not fully aware of how much D8 has evolved code-wise, but would take me by surprise not having other parts of its API dealing with arrays in general.
Maybe forms can not take advantage of it, but I think there are other cases in that it might be helpful.

If http://drupal.org/node/1876718 does not make it, a lot of contribs will hit this use-case. I would obviously prefer a cooler solution over there, but...

IMO, this solution is more generic so you get a function you can use everywhere, not only in the linked issue. More like a toolbox function. And use this in #1876718: Allow modules to inject columns into tables more easily, of course.
This would have the nice side benefit of being safely backportable as an API addition to 7.x as drupal_array_insert() for instance ;)
Even more code could benefit.

(Tentatively changing component to better reflect this)

Would this still be useful for fields with deltas? If not, I'd say this can be closed as a won't fix.

What gives strength to Drupal is its great API which allow developpers to (almost) always find the tool for their needs. Implementing this function has no cost for performances nor maintenance because its code is quite simple so I think we should just do it. We do not need endless topics about such kind of tiny problems.

The main use case in which I needed it was to inject a new filter into a view. Views' code is full of these string indexed arrays and I am sure we could find some other examples where it could help.

Maybe the good practice would be to have weight on everything but as long as we have to deal with contributed modules we cannot ensure that this will happen.

Here's an update that adds tests for the three cases of array insertion (before, middle, end) as well as does some minor documentation style fixes.

+++ b/core/lib/Drupal/Component/Utility/NestedArray.php
@@ -342,4 +342,43 @@ public static function mergeDeepArray(array $arrays, $preserve_integer_keys = FA
+    $done = FALSE;
...
+        $done = TRUE;

It seems $done is only needed in case there are 2 array keys that are identical to the specified $key. But I don't think this is possible in PHP. Can someone elaborate?

+++ b/core/lib/Drupal/Component/Utility/NestedArray.php
@@ -342,4 +342,43 @@ public static function mergeDeepArray(array $arrays, $preserve_integer_keys = FA
+      if ($array_key == $key && !$done) {

Can we get some braces around the first condition here please. That would make it less ambiguous.

To me, it looks like $done helps at least speed the for loop now by short-circuitting the if as I have now swapped conditions' order. Also, it covers the case if there is no key found at all to insert after/before. However I did not made any further test.
But if there are still valid concerns, some of them could be written as tests, as well. This could make safer later speed enhancements that might arise before RTBC, too.
Reroll of deviantart's patch with braces as per #57 and swapped conditions.
So, the interdiff:

31c42
< +      if ($array_key == $key && !$done) {
---
> +      if (!$done && ($array_key == $key)) {
116a128,130
> -- 

#58: drupal--66183--array_insert--58.patch queued for re-testing.

#58: drupal--66183--array_insert--58.patch queued for re-testing.

NestedArrayUnitTest.php file has been moved to NestedArrayTest.php, rebase'n'reroll of #58.

If we are going to add it to NestedArray shouldn't it be, you know, nested?

63: drupal--66183--array_insert--63.patch queued for re-testing.

Patch applies for me and seems to work. Tests are all green.

Patch does not apply for me:

tdm:d8 thedavidmeister$ git apply drupal--66183--array_insert--63.patch 
error: patch failed: core/tests/Drupal/Tests/Component/Utility/NestedArrayTest.php:160
error: core/tests/Drupal/Tests/Component/Utility/NestedArrayTest.php: patch does not apply

But after re-roll I think this is RTBC.

Also, I came up against this problem the other day just generally working with renderable arrays so +1 for a tool to make that easier.

Rerolled patch

RTBC as per #67

1. +++ b/core/lib/Drupal/Component/Utility/NestedArray.php
   @@ -344,4 +344,43 @@ public static function mergeDeepArray(array $arrays, $preserve_integer_keys = FA
   +   * Values from $insert_array are inserted after (or before) $key in $array. If
   +   * $key is not found, $insert_array is appended to $array using array_merge().
   

   The "in $array" part sounds weird to me. Suggestion "Values from $insert_array are inserted into $array after $key."

   Also is there any specific reason to support a non-existing $key explicitly? I can't come up with a use-case for that, to be honest.

2. +++ b/core/lib/Drupal/Component/Utility/NestedArray.php
   @@ -344,4 +344,43 @@ public static function mergeDeepArray(array $arrays, $preserve_integer_keys = FA
   +   *   The array to insert into. Passed by reference and altered in place.
   

   The second sentence is not actually a full sentence. I would suggest simply "The array to insert into, passed by reference."

3. +++ b/core/lib/Drupal/Component/Utility/NestedArray.php
   @@ -344,4 +344,43 @@ public static function mergeDeepArray(array $arrays, $preserve_integer_keys = FA
   +   *   The key of $array to insert after
   

   Missing trailing period.

4. +++ b/core/lib/Drupal/Component/Utility/NestedArray.php
   @@ -344,4 +344,43 @@ public static function mergeDeepArray(array $arrays, $preserve_integer_keys = FA
   +   * @param bool $before
   +   *   If TRUE, insert before the given key, rather than after it.
   +   *   Defaults to inserting after.
   ...
   +  public static function insert(&$array, $key, $insert_array, $before = FALSE) {
   

   I personally dislike parameters that change the behavior of a function (and quite drastically, too).

   I would prefer separate functions insertBefore() and insertAfter().

I also tried to simplify the code logic using PHP's internal array_* functions, but the result was a little bit slower in terms of performance that's why I don't want to "officially" propose doing that, even though I find the code to much more readable. In case anyone is interested the following code achieves the same that the current does:

  public static function insertBefore(&$array, $key, $insert_array) {
    $pos = array_search($key, array_keys($array)) ?: 0;
    $array =
      array_slice($array, 0, $pos) +
      $insert_array +
      array_slice($array, $pos);
  }

Moving back to needs review at least to see if people agree with splitting the method into two. The other nitpicks are only minor and I wouldn't want to hold up this very useful utility any further.

I also realized that after adding these methods we shuld probably rename the NestedArray class to just Array as these methods have nothing to do with nested arrays. Let's leave that for a follow-up, though.

Rather than introduce insertBefore and insertAfter, why not add an $offset instead of a boolean. The default for $offset 0 would insert after, -1 would be before.

Also, I just had a thought, that it makes no sense to append the insert array at the end of an array if "before" was set.

How much slower is that code really? it's a little difficult when someone says "a little bit slower/faster" without posting their benchmarks/profiling or how to reproduce as the subsequent conversation often ends up taking it as a fact.

The extra legibility could easily be worth a tiny slowdown (I must admit, that foreach did my head in a bit too, and if I had to pause to think I'm sure others will too), I think it's *unlikely* (I won't say impossible :P) to see a function like this on a critical performance path in the wild.

One thing, with the array_slice() approach, the PHP docs say that keys are not preserved without TRUE passed as a fourth parameter.

Consider:

<?php

$array = array('a', 'b', 'c');
$insert_array = array('one' => 'two');
$key = 1;


$pos = array_search($key, array_keys($array)) ?: 0;
$array = array_slice($array, 0, $pos) + $insert_array + array_slice($array, $pos);

var_dump($array);

we get:

array(3) {
  [0]=>
  string(1) "a"
  ["one"]=>
  string(3) "two"
  [1]=>
  string(1) "c"
}

$pos = array_search($key, array_keys($array)) ?: 0;
$array = array_slice($array, 0, $pos, TRUE) + $insert_array + array_slice($array, $pos, NULL, TRUE);

works for the above example

What about this?

function insert(&$array, $key, $insert_array, $offset = 0) {
  $pos = isset($array[$key]) ? array_search($key, array_keys($array)) + $offset : 0;
  $array = array_slice($array, 0, $pos, TRUE) + $insert_array + array_slice($array, $pos, NULL, TRUE);
}

If offset is 0 then the insert array will appear immediately before $key, any numeric offset will move the insert array forwards and backwards (so setting offset = 1 has the same effect as setting $before to FALSE in #69). Setting an offset larger than the size of the array sticks the insert array at the start or end of the array as appropriate.

I used isset() as it is fast and allows us to avoid searching for things that don't exist. If the key does not exist, $insert_array will be added to the start of $array.

hmm, because of use of + for array merging, we get weird behaviour with indexed arrays.

$array = array('a', 'b', 'c');
$insert_array = array('one', 'two');
$key = 1;
$offset = 0;

$pos = isset($array[$key]) ? array_search($key, array_keys($array)) + $offset : 0;
$array = array_slice($array, 0, $pos, TRUE) + $insert_array + array_slice($array, $pos, NULL, TRUE);

var_dump($array);

results in:

array(3) {
  [0]=>
  string(1) "a"
  [1]=>
  string(3) "two"
  [2]=>
  string(1) "c"
}

$pos = isset($array[$key]) ? array_search($key, array_keys($array)) + $offset : 0;
$array = array_merge(array_slice($array, 0, $pos, TRUE), $insert_array, array_slice($array, $pos, NULL, TRUE));

This can handle the cases in #72, #75.

https://ideone.com/j45dxV

I'd suggest that based on how easy it is to make mistakes with array functions, as demonstrated above, we should extend our test coverage to include indexed arrays and not just associative ones.

Reroll.

Rebase & reroll.

Completely ignoring #72 through #76?

> Rather than introduce insertBefore and insertAfter, why not add an $offset instead of a boolean. The default for $offset 0 would insert after, -1 would be before.

I think that makes it less legible, not more.

> I would prefer separate functions insertBefore() and insertAfter().

That would certainly be unambiguous. Those could both wrap around a protected method with the common code.

> I also realized that after adding these methods we shuld probably rename the NestedArray class to just Array as these methods have nothing to do with nested arrays. Let's leave that for a follow-up, though.

Can't rename it now, and NestedArray is a good name for the nester array helper methods. We could add an Array class to go alongside it though.

... though on reflection, it occurs to me that we probably can't call a class 'Array' as that's reserved in PHP.

Anyone care to bikeshed a better name?

Brainwave -- how about we call the class AssociativeArray? Since numeric arrays won't need this as they can use array_splice().

> Also is there any specific reason to support a non-existing $key explicitly? I can't come up with a use-case for that, to be honest.

Agreed. I've removed that.

> I'd suggest that based on how easy it is to make mistakes with array functions, as demonstrated above, we should extend our test coverage to include indexed arrays and not just associative ones.

I don't think this should cater for indexed arrays. If you want to insert something into an indexed array, can't you just use array_splice()? I don't think there are cases where you'd have an indexed array and want to insert an associative key into it.

> Completely ignoring #72 through #76?

I've left off the changes suggested in those comments. Perhaps they should be added, but I don't currently feel alert enough to parse expressions like:

$array = array_slice($array, 0, $pos, TRUE) + $insert_array + array_slice($array, $pos, NULL, TRUE);

Changes from previous patches:

- code is moved to a new utility class, AssociativeArray, since NestedArray doesn't make sense for this.
- two methods rather than one, insertBefore and insertAfter. I think this makes it much clearer than having a boolean parameter.
- removed support for a non-existent $key, as per previous comments.

Yes, array_splice works fine for numerically indexed arrays. But I think it'd be overall better DX to not have to worry about numeric vs associative, and to provide an InsertArray class (similarly named to DiffArray) that supports both with one method.

> But I think it'd be overall better DX to not have to worry about numeric vs associative

Numeric values should work with the current brute force approach code -- one advantage over the use of PHP array functions.

Though

      if (!$done && ($array_key == $key)) {

That should be a strict comparison, in case we have keys 0 and FALSE and ''.

One thing that I'm confused about:

  protected function verifyArrayOrder($array, $expectedArray) {
    reset($array);
    foreach ($expectedArray as $expectedValue) {
      $this->assertEquals(current($array), $expectedValue, 'Arrays contain identical values.');
      next($array);
    }
  }

How is this assertion better/different from assertSame()? Is it just that this code predates the use of PHPUnit in Drupal?

> How is this assertion better/different from assertSame()? Is it just that this code predates the use of PHPUnit in Drupal?

Turns out it's the same.

> Numeric values should work with the current brute force approach code -- one advantage over the use of PHP array functions.

They don't... I've switched to the approach from #76, although that too had mistakes with the $offset.

Changes since last patch:

- renamed to InsertArray
- use assertSame() instead of custom helper; be explicit about what we expect rather than faff with existing arrays -- it makes the test harder to read and debug
- added testing for numeric arrays
- throw an exception if the array doesn't contain $key

tested #93 in a hook_form_alter where I wanted to add a render array in the form array, works well.

Re #91, #93: it's not actually the same.

$a = [3 => 3, 2 => 2, 1 => 1];
$b = [4 => 4];
InsertArray::insertBefore($a, '1', $b);
var_export($a);

This does not return the expected result:

// It returns
array (
  0 => 3,
  1 => 2,
  2 => 4,
  3 => 1,
)
// instead of
array (
  3 => 3,
  2 => 2,
  4 => 4,
  1 => 1,
)

To fix it, we can replace the array_merge() with the array addition operator:

// instead of
    $array = array_merge(
      $array_before,
      $insert_array,
      $array_after
    );
// do
    $array = $array_before + $insert_array + $array_after;

However there is a behavior change: when there are duplicate keys, array_merge replaces values in the first array with the later, while the operator keeps values in the first array, and it is even more complicated when merge 3 arrays.

Should we reduce the scope of this class? By saying that 1/ if we support array with numeric keys 2/ what is the expected behaviors when there are duplicated keys. How many places in core that can use of this new utility class? We can then decide on which use cases should it support and how much effort could we spend on this class.

My 2c in this 14 year old issue.

Finally taken the time to get my head around #99!

The problem with changing to using the array union + operator instead of array_merge() is that it won't re-index numeric keys when we expect it to. So if we have:

// original
        [
          'first item',
          'third item',
        ],
// insert
        [
          'second item',
        ],
// insert: before 1

because these arrays are numeric, we'd expect to get something with keys 0, 1, 2.

> Should we reduce the scope of this class? By saying that 1/ if we support array with numeric keys 2/ what is the expected behaviors when there are duplicated keys. How many places in core that can use of this new utility class? We can then decide on which use cases should it support and how much effort could we spend on this class.

I'm inclined to say this class should only support associative arrays, that is, any keys that happen to be numbered are treated as if they were strings, and keys will NOT be re-indexed.

> what is the expected behaviors when there are duplicated keys

We should check for that and throw an exception.