drupal_alter

  1. drupal
    1. 8
    2. 6 common.inc
    3. 7
Versions
7 – 8 drupal_alter($type, &$data, &$context1 = NULL, &$context2 = NULL)
6 drupal_alter($type, &$data)

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.

A maximum of 2 alterable arguments is supported. In case more arguments need to be passed and alterable, modules provide additional variables assigned by reference in the last $context argument:

<?php
  $context = array(
    'alterable' => &$alterable,
    'unalterable' => $unalterable,
    'foo' => 'bar',
  );
  drupal_alter('mymodule_data', $alterable1, $alterable2, $context);
?>

Note that objects are always passed by reference in PHP5. If it is absolutely required that no implementation alters a passed object in $context, then an object needs to be cloned:

<?php
  $context = array(
    'unalterable_object' => clone $object,
  );
  drupal_alter('mymodule_data', $data, $context);
?>

Parameters

$type A string describing the type of the alterable $data. 'form', 'links', 'node_content', and so on are several examples. Alternatively can be an array, in which case hook_TYPE_alter() is invoked for each value in the array, ordered first by module, and then for each module, in the order of values in $type. For example, when Form API is using drupal_alter() to execute both hook_form_alter() and hook_form_FORM_ID_alter() implementations, it passes array('form', 'form_' . $form_id) for $type.

$data The variable that will be passed to hook_TYPE_alter() implementations to be altered. The type of this variable depends on the value of the $type argument. For example, when altering a 'form', $data will be a structured array. When altering a 'profile', $data will be an object.

$context1 (optional) An additional variable that is passed by reference.

$context2 (optional) An additional variable that is passed by reference. If more context needs to be provided to implementations, then this should be an associative array as described above.

▾ 90 functions call drupal_alter()

actions_list in includes/actions.inc
Discovers all available actions by invoking hook_action_info().
ajax_render in includes/ajax.inc
Render a commands array into JSON.
archiver_get_info in includes/common.inc
Retrieves a list of all available archivers.
batch_process in includes/form.inc
Processes the batch.
comment_view in modules/comment/comment.module
Generate an array for rendering the given comment.
contextual_pre_render_links in modules/contextual/contextual.module
Build a renderable array for contextual links.
country_get_list in includes/locale.inc
Get list of all predefined and custom countries.
dashboard_region_descriptions in modules/dashboard/dashboard.module
Return an array of dashboard region descriptions, keyed by region name.
DrupalAlterTestCase::testDrupalAlter in modules/simpletest/tests/common.test
drupal_cron_run in includes/common.inc
Executes a cron run when called.
drupal_deliver_page in includes/common.inc
Delivers a page callback result to the browser in the appropriate format.
drupal_get_complete_schema in includes/bootstrap.inc
Get the whole database schema.
drupal_get_css in includes/common.inc
Returns a themed representation of all stylesheets that should be attached to the page.
drupal_get_filetransfer_info in includes/common.inc
Drupal FileTransfer registry.
drupal_get_html_head in includes/common.inc
Retrieve output to be displayed in the HEAD tag of the HTML page.
drupal_get_js in includes/common.inc
Returns a themed presentation of all JavaScript code for the current page.
drupal_get_library in includes/common.inc
Retrieves information for a JavaScript/CSS library.
drupal_get_updaters in includes/common.inc
Drupal Updater registry.
drupal_goto in includes/common.inc
Send the user to a different Drupal page.
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.
drupal_render_page in includes/common.inc
Renders the page, including all theming.
element_info in includes/common.inc
Retrieve the default properties for the defined element type.
EntityFieldQuery::execute in includes/entity.inc
Executes the query.
entity_get_info in includes/common.inc
Get the entity info array of an entity type.
field_attach_prepare_translation in modules/field/field.attach.inc
Prepares an entity for translation.
field_attach_preprocess in modules/field/field.attach.inc
Populate the template variables with the field values available for rendering.
field_attach_view in modules/field/field.attach.inc
Returns a renderable array for the fields on an entity.
field_available_languages in modules/field/field.multilingual.inc
Collects the available languages for the given entity type and field.
field_default_form in modules/field/field.form.inc
Create a separate form element for each field.
field_extra_fields_get_display in modules/field/field.module
Returns the display settings to use for pseudo-fields in a given view mode.
field_get_display in modules/field/field.module
Returns the display settings to use for an instance in a given view mode.
field_language in modules/field/field.multilingual.inc
Returns the display language for the fields attached to the given entity.
field_multiple_value_form in modules/field/field.form.inc
Special handling to create form elements for multiple values.
field_view_field in modules/field/field.module
Returns a renderable array for the value of a single field in an entity.
file_create_url in includes/file.inc
Creates a web-accessible URL for a stream to an external or local file.
file_file_download in modules/file/file.module
Implements hook_file_download().
file_get_stream_wrappers in includes/file.inc
Drupal stream wrapper registry.
file_mimetype_mapping in includes/file.mimetypes.inc
Return an array of MIME extension mappings.
filter_get_filters in modules/filter/filter.module
Return a list of all filters provided by modules.
format_username in includes/common.inc
Format a username.
image_effect_definitions in modules/image/image.module
Pull in image effects exposed by modules implementing hook_image_effect_info().
image_styles in modules/image/image.module
Get an array of all styles and their settings.
language_fallback_get_candidates in includes/language.inc
Return the possible fallback languages ordered by language weight.
language_negotiation_get_switch_links in includes/language.inc
Return the language switch links for the given language.
language_negotiation_info in includes/language.inc
Return all the defined language providers.
language_types_info in includes/language.inc
Return all the defined language types.
menu_contextual_links in includes/menu.inc
Retrieve contextual links for a system object based on registered local tasks.
menu_execute_active_handler in includes/menu.inc
Execute the page callback associated with the current path.
menu_get_active_breadcrumb in includes/menu.inc
Get the breadcrumb for the current page, as determined by the active trail.
menu_get_item in includes/menu.inc
Get a router item.
menu_link_save in includes/menu.inc
Saves a menu link.
menu_local_tasks in includes/menu.inc
Collects the local tasks (tabs), action links, and the root path.
menu_router_build in includes/menu.inc
Collect and alter the menu definitions.
module_implements in includes/module.inc
Determine which modules are implementing a hook.
NodeAccessRecordsUnitTest::testNodeAccessRecords in modules/node/node.test
Create a node and test the creation of node access rules.
node_access_acquire_grants in modules/node/node.module
Gets the list of node access grants and writes them to the database.
node_access_grants in modules/node/node.module
Fetch an array of permission IDs granted to the given user ID.
node_view in modules/node/node.module
Generate an array for rendering the given node.
openid_discovery in modules/openid/openid.module
Perform discovery on a claimed ID to determine the OpenID provider endpoint.
openid_normalize in modules/openid/openid.inc
Normalize the given identifier.
path_get_admin_paths in includes/path.inc
Get a list of administrative and non-administrative paths.
SelectQuery::preExecute in includes/database/select.inc
Generic preparation and validation for a SELECT query.
simpletest_test_get_all in modules/simpletest/simpletest.module
Get a list of all of the tests provided by the system.
system_themes_page in modules/system/system.admin.inc
Menu callback; displays a listing of all themes.
taxonomy_term_view in modules/taxonomy/taxonomy.module
Generate an array for rendering the given term.
token_generate in includes/token.inc
Generates replacement values for a list of tokens.
token_info in includes/token.inc
Returns metadata describing supported tokens.
trigger_assign in modules/trigger/trigger.admin.inc
Builds the form that allows users to assign actions to triggers.
update_calculate_project_data in modules/update/update.compare.inc
Calculate the current update status of all projects on the site.
update_get_projects in modules/update/update.compare.inc
Fetch an array of installed and enabled projects.
url in includes/common.inc
Generates an internal or external URL.
user_cancel_methods in modules/user/user.pages.inc
Helper function to return available account cancellation methods.
user_view in modules/user/user.module
Generate an array for rendering the given user.
xmlrpc_server in includes/xmlrpcs.inc
Invokes XML-RPC methods on this server.
_block_load_blocks in modules/block/block.module
Load blocks information from the database.
_block_rehash in modules/block/block.module
Update the 'block' DB table with the blocks currently exported by modules.
_block_render_blocks in modules/block/block.module
Render the content and subject for a set of blocks.
_field_info_collate_fields in modules/field/field.info.inc
Collates all information on existing fields and instances.
_field_info_collate_types in modules/field/field.info.inc
Collates all information on field types, widget types and related structures.
_field_info_prepare_field in modules/field/field.info.inc
Prepares a field definition for the current run-time context.
_menu_link_translate in includes/menu.inc
This function is similar to _menu_translate() but does link-specific preparation such as always calling to_arg functions
_registry_update in includes/registry.inc
Does the work for registry_update().
_system_date_formats_build in modules/system/system.module
Builds and returns information about available date formats.
_system_date_format_types_build in modules/system/system.module
Builds and returns information about available date types.
_system_rebuild_module_data in modules/system/system.module
Helper function to scan and collect module .info data.
_system_rebuild_theme_data in modules/system/system.module
Helper function to scan and collect theme .info data and their engines.
_theme_build_registry in includes/theme.inc
Build the theme registry cache.
_theme_test_alter in modules/simpletest/tests/theme_test.module
Page callback, calls drupal_alter().
_trigger_get_all_info in modules/trigger/trigger.module
Retrieves and caches information from hook_trigger_info() implementations.

Code

includes/module.inc, line 904

<?php
function drupal_alter($type, &$data, &$context1 = NULL, &$context2 = NULL) {
  // Use the advanced drupal_static() pattern, since this is called very often.
  static $drupal_static_fast;
  if (!isset($drupal_static_fast)) {
    $drupal_static_fast['functions'] = &drupal_static(__FUNCTION__);
  }
  $functions = &$drupal_static_fast['functions'];

  // Most of the time, $type is passed as a string, so for performance,
  // normalize it to that. When passed as an array, usually the first item in
  // the array is a generic type, and additional items in the array are more
  // specific variants of it, as in the case of array('form', 'form_FORM_ID').
  if (is_array($type)) {
    $cid = implode(',', $type);
    $extra_types = $type;
    $type = array_shift($extra_types);
    // Allow if statements in this function to use the faster isset() rather
    // than !empty() both when $type is passed as a string, or as an array with
    // one item.
    if (empty($extra_types)) {
      unset($extra_types);
    }
  }
  else {
    $cid = $type;
  }

  // Some alter hooks are invoked many times per page request, so statically
  // cache the list of functions to call, and on subsequent calls, iterate
  // through them quickly.
  if (!isset($functions[$cid])) {
    $functions[$cid] = array();
    $hook = $type . '_alter';
    $modules = module_implements($hook);
    if (!isset($extra_types)) {
      // For the more common case of a single hook, we do not need to call
      // function_exists(), since module_implements() returns only modules with
      // implementations.
      foreach ($modules as $module) {
        $functions[$cid][] = $module . '_' . $hook;
      }
    }
    else {
      // For multiple hooks, we need $modules to contain every module that
      // implements at least one of them.
      $extra_modules = array();
      foreach ($extra_types as $extra_type) {
        $extra_modules = array_merge($extra_modules, module_implements($extra_type . '_alter'));
      }
      // If any modules implement one of the extra hooks that do not implement
      // the primary hook, we need to add them to the $modules array in their
      // appropriate order.
      if (array_diff($extra_modules, $modules)) {
        // Order the modules by the order returned by module_list().
        $modules = array_intersect(module_list(), array_merge($modules, $extra_modules));
      }
      foreach ($modules as $module) {
        // Since $modules is a merged array, for any given module, we do not
        // know whether it has any particular implementation, so we need a
        // function_exists().
        $function = $module . '_' . $hook;
        if (function_exists($function)) {
          $functions[$cid][] = $function;
        }
        foreach ($extra_types as $extra_type) {
          $function = $module . '_' . $extra_type . '_alter';
          if (function_exists($function)) {
            $functions[$cid][] = $function;
          }
        }
      }
    }
    // Allow the theme to alter variables after the theme system has been
    // initialized.
    global $theme, $base_theme_info;
    if (isset($theme)) {
      $theme_keys = array();
      foreach ($base_theme_info as $base) {
        $theme_keys[] = $base->name;
      }
      $theme_keys[] = $theme;
      foreach ($theme_keys as $theme_key) {
        $function = $theme_key . '_' . $hook;
        if (function_exists($function)) {
          $functions[$cid][] = $function;
        }
        if (isset($extra_types)) {
          foreach ($extra_types as $extra_type) {
            $function = $theme_key . '_' . $extra_type . '_alter';
            if (function_exists($function)) {
              $functions[$cid][] = $function;
            }
          }
        }
      }
    }
  }

  foreach ($functions[$cid] as $function) {
    $function($data, $context1, $context2);
  }
}
?>