The parameters accepted from drupal_bootstrap() are two; the second is defined as follows:

$new_phase: A boolean, set to FALSE if calling drupal_bootstrap() from inside a function called from drupal_bootstrap() (recursion).

I am not clear what that means, considering that statistics_exit() calls drupal_bootstrap() using just one argument, thus using the default value (TRUE) for the second one.
hook_exit() is invoked from _drupal_bootstrap_page_cache(), and statistics_exit() should be considered a function called from drupal_bootstrap() that calls drupal_bootstrap().

Yet, statistics_exit() is not using FALSE as second argument of drupal_bootstrap().

The only functions I found that use FALSE as second parameter are module_hook_info(), and _drupal_bootstrap_page_cache(), which contain the following code.

  // module_hook_info()
  // This function is indirectly invoked from bootstrap_invoke_all(), in which
  // case common.inc, subsystems, and modules are not loaded yet, so it does not
  // make sense to support hook groups resp. lazy-loaded include files prior to
  // full bootstrap.
  if (drupal_bootstrap(NULL, FALSE) != DRUPAL_BOOTSTRAP_FULL) {
    return array();
  // _drupal_bootstrap_page_cache()
  // Check for a cache mode force from settings.php.
  if (variable_get('page_cache_without_database')) {
    $cache_enabled = TRUE;
  else {
    $cache_enabled = variable_get('cache');

From the code of the first function I could understand I should use FALSE when I need to get the current bootstrap phase, and in that case I would use NULL as first argument.
From the code of the second function, I could understand that the second parameter is an internal parameter, I should not pass in my functions, as the only case a function of mine is being called from drupal_bootstrap() (also indirectly, through a function that is called from drupal_bootstrap()) is when I implement hook_boot(), or hook_exit().

Did I misunderstand what said in the drupal_bootstrap() documentation? If it so, when exactly should a call to drupal_bootstrap() use a value for the second parameter that is different from its default value?


Without looking more closely, I can't say why statistics_exit() doesn't use the second parameter, but to answer your question...

The drupal_bootstrap() function only ever needs to be called with $new_phase = FALSE to prevent an infinite loop inside the core bootstrap code. Unless you're modifying core, you'll always want to leave the second parameter at its default value (TRUE).

The key is in this part of drupal_bootstrap():

// When not recursing, store the phase name so it's not forgotten while
// recursing.
if ($new_phase) {
  $final_phase = $phase;

Calls to drupal_bootstrap() outside the bootstrap process always specify the final phase to bootstrap to (or only get the current phase, in which case, the second parameter doesn't matter). When you call drupal_boostrap(), you'll be initiating the bootstrap process and setting the static $final_phase variable, so you'll need $new_phase = TRUE.

  • I would add that there are many Drupal core functions that use a parameter though to be use from Drupal core, which uses it and sets it to a value different from the default value. In this case, $new_phase could be used also from contrubuted modules, in a function that calls drupal_bootstrap() and that is called from drupal_bootstrap(). Probably there are very few modules that need to use $new_phase.
    – apaderno
    Dec 20 '21 at 10:57

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.