module.inc 20.8 KB
Newer Older
1 2 3
<?php
// $Id$

4 5 6 7 8
/**
 * @file
 * API for loading and interacting with Drupal modules.
 */

9
/**
10
 * Load all the modules that have been enabled in the system table.
11 12 13 14 15 16 17
 * 
 * @param $bootstrap
 *   Whether to load only the reduced set of modules loaded in "bootstrap mode"
 *   for cached pages. See bootstrap.inc.
 * @return
 *   If $bootstrap is NULL, return a boolean indicating whether all modules
 *   have been loaded.
18
 */
19
function module_load_all($bootstrap = FALSE) {
20 21 22 23 24 25 26 27
  static $has_run = FALSE;

  if (isset($bootstrap)) {
    foreach (module_list(TRUE, $bootstrap) as $module) {
      drupal_load('module', $module);
    }
    // $has_run will be TRUE if $bootstrap is FALSE.
    $has_run = !$bootstrap;
28
  }
29
  return $has_run;
30 31
}

32

33
/**
34 35
 * Collect a list of all loaded modules. During the bootstrap, return only
 * vital modules. See bootstrap.inc
36 37 38 39
 *
 * @param $refresh
 *   Whether to force the module list to be regenerated (such as after the
 *   administrator has changed the system settings).
40 41 42
 * @param $bootstrap
 *   Whether to return the reduced set of modules loaded in "bootstrap mode"
 *   for cached pages. See bootstrap.inc.
43
 * @param $sort
44 45
 *   By default, modules are ordered by weight and module name. Set this option
 *   to TRUE to return a module list ordered only by module name.
46 47 48
 * @param $fixed_list
 *   (Optional) Override the module list with the given modules. Stays until the
 *   next call with $refresh = TRUE.
49 50 51 52
 * @return
 *   An associative array whose keys and values are the names of all loaded
 *   modules.
 */
53
function module_list($refresh = FALSE, $bootstrap = FALSE, $sort = FALSE, $fixed_list = NULL) {
54
  static $list = array(), $sorted_list;
55

56
  if (empty($list) || $refresh || $fixed_list) {
Dries's avatar
Dries committed
57
    $list = array();
58
    $sorted_list = NULL;
59 60 61 62 63
    if ($fixed_list) {
      foreach ($fixed_list as $name => $module) {
        drupal_get_filename('module', $name, $module['filename']);
        $list[$name] = $name;
      }
64 65
    }
    else {
66 67 68
      // As this is the $refresh case, make sure that system_list() returns
      // fresh data.
      drupal_static_reset('system_list');
69
      if ($bootstrap) {
70
        $list = system_list('bootstrap');
71 72
      }
      else {
73
        $list = system_list('module_enabled');
74
      }
75 76
    }
  }
77 78 79 80 81 82 83
  if ($sort) {
    if (!isset($sorted_list)) {
      $sorted_list = $list;
      ksort($sorted_list);
    }
    return $sorted_list;
  }
84 85 86
  return $list;
}

87 88 89 90
/**
 * Build a list of bootstrap modules and enabled modules and themes.
 *
 * @param $type
91 92 93 94
 *   The type of list to return:
 *   - module_enabled: All enabled modules.
 *   - bootstrap: All enabled modules required for bootstrap.
 *   - theme: All themes.
95 96
 *
 * @return
97 98 99
 *   An associative array of modules or themes, keyed by name, and having the
 *   respective database row as value. For $type 'module_enabled' and
 *   'bootstrap', the array values equal the keys.
100 101 102 103 104 105 106
 *
 * @see module_list()
 * @see list_themes()
 */
function system_list($type) {
  $lists = &drupal_static(__FUNCTION__);

107 108 109 110 111 112 113 114 115
  // For bootstrap modules, attempt to fetch the list from cache if possible.
  // if not fetch only the required information to fire bootstrap hooks
  // in case we are going to serve the page from cache.
  if ($type == 'bootstrap') {
    if ($cached = cache_get('bootstrap_modules', 'cache_bootstrap')) {
      $bootstrap_list = $cached->data;
    }
    else {
      $bootstrap_list = db_query("SELECT name, filename FROM {system} WHERE status = 1 AND bootstrap = 1 AND type = 'module' ORDER BY weight ASC, name ASC")->fetchAllAssoc('name');
116
      cache_set('bootstrap_modules', $bootstrap_list, 'cache_bootstrap');
117 118 119 120 121 122 123 124 125 126 127 128
    }
    foreach ($bootstrap_list as $module) {
      // Prime the drupal_get_filename() static cache to avoid subsequent
      // queries to retrieve module filename.
      drupal_get_filename('module', $module->name, $module->filename);
    }
    // We only return the module names here since module_list() doesn't need
    // the filename itself.
    $lists['bootstrap'] = array_keys($bootstrap_list);
  }
  // Otherwise build the list for enabled modules and themes.
  elseif (!isset($lists)) {
129 130 131 132
    $lists = array(
      'module_enabled' => array(),
      'theme' => array(),
    );
133 134 135 136 137
    // The module name (rather than the filename) is used as the fallback
    // weighting in order to guarantee consistent behavior across different
    // Drupal installations, which might have modules installed in different
    // locations in the file system. The ordering here must also be
    // consistent with the one used in module_implements().
138
    $result = db_query("SELECT * FROM {system} ORDER BY weight ASC, name ASC");
139
    foreach ($result as $record) {
140
      if ($record->type == 'module' && $record->status) {
141
        // Build a list of all enabled modules.
142
        $lists['module_enabled'][$record->name] = $record->name;
143
      }
144
      // Build a list of themes.
145 146 147 148 149 150 151
      if ($record->type == 'theme') {
        $lists['theme'][$record->name] = $record;
      }

      // Additionally prime drupal_get_filename() with the filename and type
      // for each record, this prevents subsequent database lookups when
      // drupal_get_filename() is called without the 'file' argument.
152 153 154
      if ($record->status) {
        drupal_get_filename($record->type, $record->name, $record->filename);
      }
155 156 157 158 159 160
    }
  }

  return $lists[$type];
}

161 162 163 164 165 166 167 168
/**
 * Reset all system_list() caches.
 */
function system_list_reset() {
  drupal_static_reset('system_list');
  cache_clear_all('bootstrap_modules', 'cache_bootstrap');
}

169
/**
170
 * Find dependencies any level deep and fill in required by information too.
171 172 173
 *
 * @param $files
 *   The array of filesystem objects used to rebuild the cache.
174
 * @return
175 176 177 178 179
 *   The same array with the new keys for each module:
 *   - requires: An array with the keys being the modules that this module
 *     requires.
 *   - required_by: An array with the keys being the modules that will not work
 *     without this module.
180
 */
181
function _module_build_dependencies($files) {
182
  require_once DRUPAL_ROOT . '/includes/graph.inc';
183 184 185 186
  $roots = $files;
  foreach ($files as $filename => $file) {
    $graph[$file->name]['edges'] = array();
    if (isset($file->info['dependencies']) && is_array($file->info['dependencies'])) {
187 188 189 190
      foreach ($file->info['dependencies'] as $dependency) {
        $dependency_data = drupal_parse_dependency($dependency);
        $graph[$file->name]['edges'][$dependency_data['name']] = $dependency_data;
        unset($roots[$dependency_data['name']]);
191 192
      }
    }
193 194 195
  }
  drupal_depth_first_search($graph, array_keys($roots));
  foreach ($graph as $module => $data) {
196
    $files[$module]->required_by = isset($data['reverse_paths']) ? $data['reverse_paths'] : array();
197 198 199
    $files[$module]->requires = isset($data['paths']) ? $data['paths'] : array();
    $files[$module]->sort = $data['weight'];
  }
Steven Wittens's avatar
Steven Wittens committed
200 201 202
  return $files;
}

203 204 205 206 207 208 209 210
/**
 * Determine whether a given module exists.
 *
 * @param $module
 *   The name of the module (without the .module extension).
 * @return
 *   TRUE if the module is both installed and enabled.
 */
211
function module_exists($module) {
212
  $list = module_list();
213
  return isset($list[$module]);
214 215
}

Steven Wittens's avatar
Steven Wittens committed
216 217 218 219 220
/**
 * Load a module's installation hooks.
 */
function module_load_install($module) {
  // Make sure the installation API is available
221
  include_once DRUPAL_ROOT . '/includes/install.inc';
Steven Wittens's avatar
Steven Wittens committed
222

223
  module_load_include('install', $module);
224 225 226 227
}

/**
 * Load a module include file.
228
 *
229 230
 * Examples:
 * @code
231
 *   // Load node.admin.inc from the node module.
232
 *   module_load_include('inc', 'node', 'node.admin');
233
 *   // Load content_types.inc from the node module.
234
 *   module_load_include('inc', 'node', 'content_types');
235
 * @endcode
236
 *
237 238 239
 * Do not use this function to load an install file. Use module_load_install()
 * instead.
 *
240 241 242 243 244
 * @param $type
 *   The include file's type (file extension).
 * @param $module
 *   The module to which the include file belongs.
 * @param $name
245
 *   Optionally, specify the base file name (without the $type extension).
246
 *   If not set, $module is used.
247 248 249 250 251 252
 */
function module_load_include($type, $module, $name = NULL) {
  if (empty($name)) {
    $name = $module;
  }

253
  if (function_exists('drupal_get_path')) {
254 255 256 257 258
    $file = DRUPAL_ROOT . '/' . drupal_get_path('module', $module) . "/$name.$type";
    if (is_file($file)) {
      require_once $file;
      return $file;
    }
259
  }
260
  return FALSE;
261 262 263 264 265 266 267 268 269 270
}

/**
 * Load an include file for each of the modules that have been enabled in
 * the system table.
 */
function module_load_all_includes($type, $name = NULL) {
  $modules = module_list();
  foreach ($modules as $module) {
    module_load_include($type, $module, $name);
Steven Wittens's avatar
Steven Wittens committed
271 272 273 274
  }
}

/**
275
 * Enable a given list of modules.
Steven Wittens's avatar
Steven Wittens committed
276
 *
277 278
 * @param $module_list
 *   An array of module names.
279 280
 * @param $disable_modules_installed_hook
 *   Normally just testing wants to set this to TRUE.
Steven Wittens's avatar
Steven Wittens committed
281
 */
282
function module_enable($module_list, $disable_modules_installed_hook = FALSE) {
283
  $invoke_modules = array();
284

285 286 287
  // Try to install the enabled modules and collect which were installed.
  // $module_list is not changed and already installed modules are ignored.
  $modules_installed = array_filter($module_list, '_drupal_install_module');
288
  foreach ($module_list as $module) {
289 290 291 292
    $existing = db_query("SELECT status FROM {system} WHERE type = :type AND name = :name", array(
      ':type' => 'module',
      ':name' => $module))
      ->fetchObject();
293
    if ($existing->status == 0) {
294
      module_load_install($module);
295 296 297 298 299
      db_update('system')
        ->fields(array('status' => 1))
        ->condition('type', 'module')
        ->condition('name', $module)
        ->execute();
300 301
      drupal_load('module', $module);
      $invoke_modules[] = $module;
302
      watchdog('system', '%module module enabled.', array('%module' => $module), WATCHDOG_INFO);
303
    }
Steven Wittens's avatar
Steven Wittens committed
304
  }
305 306

  if (!empty($invoke_modules)) {
307
    // Refresh the module list to exclude the disabled modules.
308
    system_list_reset();
309
    module_list(TRUE);
310
    module_implements('', FALSE, TRUE);
311
    // Force to regenerate the stored list of hook implementations.
312
    registry_rebuild();
313 314
    // Refresh the schema to include the new enabled module.
    drupal_get_schema(NULL, TRUE);
315 316 317 318 319

    // If any modules were newly installed, execute the hook for them.
    if (!$disable_modules_installed_hook && !empty($modules_installed)) {
      module_invoke_all('modules_installed', $modules_installed);
    }
320 321 322 323
  }

  foreach ($invoke_modules as $module) {
    module_invoke($module, 'enable');
324
    // Check if node_access table needs rebuilding.
325 326 327
    // We check for the existence of node_access_needs_rebuild() since
    // at install time, module_enable() could be called while node.module
    // is not enabled yet.
328
    if (function_exists('node_access_needs_rebuild') && !node_access_needs_rebuild() && module_hook($module, 'node_grants')) {
329 330
      node_access_needs_rebuild(TRUE);
    }
Steven Wittens's avatar
Steven Wittens committed
331
  }
332 333

  if (!empty($invoke_modules)) {
334
    // Invoke hook_modules_enabled after all the modules have been
335 336 337
    // enabled.
    module_invoke_all('modules_enabled', $invoke_modules);
  }
Steven Wittens's avatar
Steven Wittens committed
338 339 340
}

/**
341
 * Disable a given set of modules.
Steven Wittens's avatar
Steven Wittens committed
342
 *
343 344
 * @param $module_list
 *   An array of module names.
Steven Wittens's avatar
Steven Wittens committed
345
 */
346 347 348 349
function module_disable($module_list) {
  $invoke_modules = array();
  foreach ($module_list as $module) {
    if (module_exists($module)) {
350 351 352 353 354
      // Check if node_access table needs rebuilding.
      if (!node_access_needs_rebuild() && module_hook($module, 'node_grants')) {
        node_access_needs_rebuild(TRUE);
      }

355 356
      module_load_install($module);
      module_invoke($module, 'disable');
357 358 359 360 361
      db_update('system')
        ->fields(array('status' => 0))
        ->condition('type', 'module')
        ->condition('name', $module)
        ->execute();
362
      $invoke_modules[] = $module;
363
      watchdog('system', '%module module disabled.', array('%module' => $module), WATCHDOG_INFO);
364
    }
Steven Wittens's avatar
Steven Wittens committed
365
  }
366 367

  if (!empty($invoke_modules)) {
368
    // Refresh the module list to exclude the disabled modules.
369
    system_list_reset();
370 371
    module_list(TRUE);
    module_implements('', FALSE, TRUE);
372
    // Invoke hook_modules_disabled before disabling modules,
373 374
    // so we can still call module hooks to get information.
    module_invoke_all('modules_disabled', $invoke_modules);
375
    // Force to regenerate the stored list of hook implementations.
376
    registry_rebuild();
Steven Wittens's avatar
Steven Wittens committed
377
  }
378

379
  // If there remains no more node_access module, rebuilding will be
380 381 382 383
  // straightforward, we can do it right now.
  if (node_access_needs_rebuild() && count(module_implements('node_grants')) == 0) {
    node_access_rebuild();
  }
Steven Wittens's avatar
Steven Wittens committed
384 385
}

386 387
/**
 * @defgroup hooks Hooks
Dries's avatar
 
Dries committed
388 389
 * @{
 * Allow modules to interact with the Drupal core.
390 391
 *
 * Drupal's module system is based on the concept of "hooks". A hook is a PHP
392 393 394
 * function that is named foo_bar(), where "foo" is the name of the module
 * (whose filename is thus foo.module) and "bar" is the name of the hook. Each
 * hook has a defined set of parameters and a specified result type.
395
 *
396 397 398
 * To extend Drupal, a module need simply implement a hook. When Drupal wishes
 * to allow intervention from modules, it determines which modules implement a
 * hook and calls that hook in all enabled modules that implement it.
399 400 401
 *
 * The available hooks to implement are explained here in the Hooks section of
 * the developer documentation. The string "hook" is used as a placeholder for
402 403 404
 * the module name in the hook definitions. For example, if the module file is
 * called example.module, then hook_help() as implemented by that module would
 * be defined as example_help().
405 406 407 408 409 410 411 412 413 414 415 416 417 418
 */

/**
 * Determine whether a module implements a hook.
 *
 * @param $module
 *   The name of the module (without the .module extension).
 * @param $hook
 *   The name of the hook (e.g. "help" or "menu").
 * @return
 *   TRUE if the module is both installed and enabled, and the hook is
 *   implemented in that module.
 */
function module_hook($module, $hook) {
419
  return function_exists($module . '_' . $hook);
420 421
}

Dries's avatar
 
Dries committed
422 423 424 425
/**
 * Determine which modules are implementing a hook.
 *
 * @param $hook
426
 *   The name of the hook (e.g. "help" or "menu").
427
 * @param $sort
428 429
 *   By default, modules are ordered by weight and filename, settings this option
 *   to TRUE, module list will be ordered by module name.
430
 * @param $reset
431 432 433
 *   For internal use only: Whether to force the stored list of hook
 *   implementations to be regenerated (such as after enabling a new module,
 *   before processing hook_enable).
434
 *
Dries's avatar
 
Dries committed
435 436
 * @return
 *   An array with the names of the modules which are implementing this hook.
437 438
 *
 * @see module_implements_write_cache().
Dries's avatar
 
Dries committed
439
 */
440 441
function module_implements($hook, $sort = FALSE, $reset = FALSE) {
  $implementations = &drupal_static(__FUNCTION__, array());
442

443 444 445 446 447 448 449 450 451 452 453
  // We maintain a persistent cache of hook implementations in addition to the
  // static cache to avoid looping through every module and every hook on each
  // request. Benchmarks show that the benefit of this caching outweighs the
  // additional database hit even when using the default database caching
  // backend and only a small number of modules are enabled. The cost of the
  // cache_get() is more or less constant and reduced further when non-database
  // caching backends are used, so there will be more significant gains when a
  // large number of modules are installed or hooks invoked, since this can
  // quickly lead to module_hook() being called several thousand times
  // per request.
  if ($reset) {
454
    $implementations = array();
455
    cache_set('module_implements', array(), 'cache_bootstrap');
456
    drupal_static_reset('module_hook_info');
457
    drupal_static_reset('drupal_alter');
458
    cache_clear_all('hook_info', 'cache_bootstrap');
459
    return;
460 461
  }

462 463
  // Fetch implementations from cache.
  if (empty($implementations)) {
464
    $implementations = cache_get('module_implements', 'cache_bootstrap');
465 466 467 468 469 470 471 472
    if ($implementations === FALSE) {
      $implementations = array();
    }
    else {
      $implementations = $implementations->data;
    }
  }

473
  if (!isset($implementations[$hook])) {
474
    $hook_info = module_hook_info();
475 476 477
    $implementations[$hook] = array();
    $list = module_list(FALSE, FALSE, $sort);
    foreach ($list as $module) {
478 479 480
      $include_file = FALSE;
      if (module_hook($module, $hook) || (isset($hook_info[$hook]['group']) && $include_file = module_load_include('inc', $module, $module . '.' . $hook_info[$hook]['group']) && module_hook($module, $hook))) {
        $implementations[$hook][$module] = $include_file ? $hook_info[$hook]['group'] : FALSE;
481 482 483 484 485 486
        // We added something to the cache, so write it when we are done.
        $implementations['#write_cache'] = TRUE;
      }
    }
  }
  else {
487 488 489 490 491 492
    foreach ($implementations[$hook] as $module => $group) {
      // If this hook implementation is stored in a lazy-loaded file, so include
      // that file first.
      if ($group) {
        module_load_include('inc', $module, "$module.$group");
      }
493 494 495 496 497 498 499 500
      // It is possible that a module removed a hook implementation without the
      // implementations cache being rebuilt yet, so we check module_hook() on
      // each request to avoid undefined function errors.
      if (!module_hook($module, $hook)) {
        // Clear out the stale implementation from the cache and force a cache
        // refresh to forget about no longer existing hook implementations.
        unset($implementations[$hook][$module]);
        $implementations['#write_cache'] = TRUE;
Dries's avatar
 
Dries committed
501 502
      }
    }
503
  }
Dries's avatar
 
Dries committed
504

505 506 507 508 509 510 511 512 513 514
  return array_keys($implementations[$hook]);
}

/**
 * Retrieve a list of what hooks are explicitly declared.
 */
function module_hook_info() {
  $hook_info = &drupal_static(__FUNCTION__, array());

  if (empty($hook_info)) {
515
    $cache = cache_get('hook_info', 'cache_bootstrap');
516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535
    if ($cache === FALSE) {
      // Rebuild the cache and save it.
      // We can't use module_invoke_all() here or it would cause an infinite
      // loop.
      foreach (module_list() as $module) {
        $function = $module . '_hook_info';
        if (function_exists($function)) {
          $result = $function();
          if (isset($result) && is_array($result)) {
            $hook_info = array_merge_recursive($hook_info, $result);
          }
        }
      }
      // We can't use drupal_alter() for the same reason as above.
      foreach (module_list() as $module) {
        $function = $module . '_hook_info_alter';
        if (function_exists($function)) {
          $function($hook_info);
        }
      }
536
      cache_set('hook_info', $hook_info, 'cache_bootstrap');
537 538 539 540 541 542 543
    }
    else {
      $hook_info = $cache->data;
    }
  }

  return $hook_info;
544 545
}

546 547 548 549 550 551 552
/**
 * Writes the hook implementation cache.
 *
 * @see module_implements()
 */
function module_implements_write_cache() {
  $implementations = &drupal_static('module_implements');
553 554 555 556
  // Check whether we need to write the cache. We do not want to cache hooks
  // which are only invoked on HTTP POST requests since these do not need to be
  // optimized as tightly, and not doing so keeps the cache entry smaller.
  if (isset($implementations['#write_cache']) && ($_SERVER['REQUEST_METHOD'] == 'GET' || $_SERVER['REQUEST_METHOD'] == 'HEAD')) {
557
    unset($implementations['#write_cache']);
558
    cache_set('module_implements', $implementations, 'cache_bootstrap');
559 560 561
  }
}

562 563 564 565 566 567 568 569 570 571 572 573
/**
 * Invoke a hook in a particular module.
 *
 * @param $module
 *   The name of the module (without the .module extension).
 * @param $hook
 *   The name of the hook to invoke.
 * @param ...
 *   Arguments to pass to the hook implementation.
 * @return
 *   The return value of the hook implementation.
 */
574 575
function module_invoke() {
  $args = func_get_args();
576 577 578
  $module = $args[0];
  $hook = $args[1];
  unset($args[0], $args[1]);
579
  if (module_hook($module, $hook)) {
580
    return call_user_func_array($module . '_' . $hook, $args);
581 582 583 584 585 586 587 588 589 590 591 592 593
  }
}
/**
 * Invoke a hook in all enabled modules that implement it.
 *
 * @param $hook
 *   The name of the hook to invoke.
 * @param ...
 *   Arguments to pass to the hook.
 * @return
 *   An array of return values of the hook implementations. If modules return
 *   arrays from their implementations, those are merged into one array.
 */
594 595
function module_invoke_all() {
  $args = func_get_args();
596 597
  $hook = $args[0];
  unset($args[0]);
598
  $return = array();
599
  foreach (module_implements($hook) as $module) {
600
    $function = $module . '_' . $hook;
601
    if (function_exists($function)) {
602 603 604 605
      $result = call_user_func_array($function, $args);
      if (isset($result) && is_array($result)) {
        $return = array_merge_recursive($return, $result);
      }
606
      elseif (isset($result)) {
607 608
        $return[] = $result;
      }
609
    }
610 611 612 613 614 615
  }

  return $return;
}

/**
Dries's avatar
 
Dries committed
616
 * @} End of "defgroup hooks".
617 618
 */

619 620 621 622
/**
 * Array of modules required by core.
 */
function drupal_required_modules() {
623 624
  $files = drupal_system_listing('/\.info$/', 'modules', 'name', 0);
  $required = array();
625 626 627 628

  // An install profile is required and one must always be loaded.
  $required[] = drupal_get_profile();

629
  foreach ($files as $name => $file) {
630
    $info = drupal_parse_info_file($file->uri);
631 632 633 634
    if (!empty($info) && !empty($info['required']) && $info['required']) {
      $required[] = $name;
    }
  }
635

636
  return $required;
637
}