function drupal_alter

You are here

7 module.inc drupal_alter($type, &$data, &$context1 = NULL, &$context2 = NULL, &$context3 = NULL)
6 common.inc drupal_alter($type, &$data)
8 bootstrap.inc drupal_alter($type, &$data, &$context1 = NULL, &$context2 = NULL)

Hands off alterable variables to type-specific *_alter implementations.

This dispatch function hands off the passed in variables to type-specific hook_TYPE_alter() implementations in modules. It ensures a consistent interface for all altering operations.

Parameters

$type: A string describing the type of the alterable $data (e.g. 'form', 'profile').

$data: The variable that will be passed to hook_TYPE_alter() implementations to be altered. The type of this variable depends on $type. For example, when altering a 'form', $data will be a structured array. When altering a 'profile', $data will be an object. If you need to pass additional parameters by reference to the hook_TYPE_alter() functions, include them as an array in $data['__drupal_alter_by_ref']. They will be unpacked and passed to the hook_TYPE_alter() functions, before the additional ... parameters (see below).

...: Any additional parameters will be passed on to the hook_TYPE_alter() functions (not by reference), after any by-reference parameters included in $data (see above)

20 calls to drupal_alter()
actions_list in includes/actions.inc
Discover all action functions by invoking hook_action_info().
comment_render in modules/comment/comment.module
Renders comment(s).
drupal_get_schema in includes/common.inc
Get the schema definition of a table, or the whole database schema.
drupal_mail in includes/mail.inc
Compose and optionally send an e-mail message.
drupal_prepare_form in includes/form.inc
Prepares a structured form array by adding required elements, executing any hook_form_alter functions, and optionally inserting a validation token to prevent tampering.

... See full list

File

includes/common.inc, line 2920
Common functions that many Drupal modules will need to reference.

Code

function drupal_alter($type, &$data) {
  // PHP's func_get_args() always returns copies of params, not references, so
  // drupal_alter() can only manipulate data that comes in via the required first
  // param. For the edge case functions that must pass in an arbitrary number of
  // alterable parameters (hook_form_alter() being the best example), an array of
  // those params can be placed in the __drupal_alter_by_ref key of the $data
  // array. This is somewhat ugly, but is an unavoidable consequence of a flexible
  // drupal_alter() function, and the limitations of func_get_args().
  // @todo: Remove this in Drupal 7.
  if (is_array($data) && isset($data['__drupal_alter_by_ref'])) {
    $by_ref_parameters = $data['__drupal_alter_by_ref'];
    unset($data['__drupal_alter_by_ref']);
  }

  // Hang onto a reference to the data array so that it isn't blown away later.
  // Also, merge in any parameters that need to be passed by reference.
  $args = array(&$data);
  if (isset($by_ref_parameters)) {
    $args = array_merge($args, $by_ref_parameters);
  }

  // Now, use func_get_args() to pull in any additional parameters passed into
  // the drupal_alter() call.
  $additional_args = func_get_args();
  array_shift($additional_args);
  array_shift($additional_args);
  $args = array_merge($args, $additional_args);

  foreach (module_implements($type . '_alter') as $module) {
    $function = $module . '_' . $type . '_alter';
    call_user_func_array($function, $args);
  }
}

Comments

I was wondering if the first Parameter $type is not passed by reference, so the function declaration would be:

function drupal_alter(&$type, &$data) {
    ...
  }

$type never gets passed to any other functions, does it? So there's no scope for it to be modified and no reason for it to be passed by reference. It's only ever used to build the function names e.g. mymodule_{$type}_alter($data)