drupal_alter

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)

File

includes/common.inc, line 2900

Common functions that many Drupal modules will need to reference.

Code

<?php
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);
  }
}
?>