Manipulating an array (adding, removing, replacing, popping, shifting)

There are a number of useful PHP utilities for manipulating arrays. We're going to use the example here of hook_form_alter(), a hook supplied by Drupal to allow us to manipulate forms. Since forms are really just arrays of data, altering the structure of a form is synonymous with altering an array. Let's take a look at a simple $form array from the user login form, defined in user.module in the modules/user folder:

$form = array(
  '#action' => url($_GET['q'], array('query' => drupal_get_destination())),
  '#id' => 'user-login-form',
  '#validate' => user_login_default_validators(),
  '#submit' => array('user_login_submit'),
);
$form['name'] = array('#type' => 'textfield',
  '#title' => t('Username'),
  '#maxlength' => USERNAME_MAX_LENGTH,
  '#size' => 15,
  '#required' => TRUE,
);
$form['pass'] = array('#type' => 'password',
  '#title' => t('Password'),
  '#maxlength' => 60,
  '#size' => 15,
  '#required' => TRUE,
);
$form['submit'] = array('#type' => 'submit',
  '#value' => t('Log in'),
);

Adding an element to an array

In this example you can see that the $form variable is first defined, and then new variables are added to it by using the following structure:

$form[$key] = $value;

The important part here is that the $key is unique, otherwise the existing value for the key will be overwritten.

Replace an array value

That last example gives gives us a clue as to how we would override a array value. Say we wanted to replace the label on the 'Username' input to something like 'What should we call you?'. To do that, we'd do:

$form['name']['#title'] = 'What should we call you?';

Notice that we're having to change an array element that's within an array. We dig into the structure on an array using the [] brackets. Because $form['name'] is an array, and we need to identify the #title element in that array, we use $form['name']['#title'].

In Drupal, it's a convention to add a hash tag (#) to the beginning of variable names that correspond to a setting, rather than an element. This is done to avoid namespace collisions.
Removing an element from an array

To remove an item from an array, you can use the unset() function. Say we wanted to remove the password input from the above form. We'd do that with the following:

unset($form['pass']);

Moving an element off the end or beginning of an array

There are a couple of handy tools that you can use to move elements off of the beginning and end of an array - kind of tricky to do without the help of these functions. To remove the first element off an array, you would use the following:

array_shift($form);

This isn't very practical for our $form example, but believe me, it will come in handy down the road. And to remove an element off the end of an array, use the following:

array_pop($form);

These two functions also return the element that was removed, so if you wanted to do something with the element, just assign a variable to the function, as in the following:

$element_removed = array_pop($form);

There, now you're an array manipulation ninja. Go forth!