Drupal 7 Line by Line : Part 2

this post I'll start walking through one of those functions: drupal_bootstrap(). If you recallfrom Part 1 I said this function is starts up (bootstraps) all ofDrupal's mechanisms required to handle a page request. This is onlypart of the story and only half the truth. A more accuratedescription would be that it loads up only as much of Drupal'sfunctionality a php script needs so that the php script can usesthat functionality to do something.

When drupal_bootstrap is calledfrom index.php it is passed a single argument: BOOTSTRAP_FULL. Inorder for index.php (a php script) to display a web page (what thescript does) it needs Drupal to bootstrap all of its mechanisms(i.e. a full bootstrap).

Lets see what the phpDoc comment and function signature fordrupal_bootstrap() have to say:

<?php

function drupal_bootstrap($phase= NULL,$new_phase = TRUE) {?>

This basically tells us that when we call this function we haveto tell it which bootstrap phase to run by passing a value to the$phase variable. The functionaccepts a second argument $new_phase which by default is "TRUE".

Executing drupal_bootstrap(BOOTSTRAP_FULL)

So the first thing that the function does when its run is definea staticvariable called $phases. Thatvariable is assigned an array that is populated with the constantsthat represent the 7 phases of the bootstrap process.

<?php
  static $phases =array(
   DRUPAL_BOOTSTRAP_CONFIGURATION,
   DRUPAL_BOOTSTRAP_PAGE_CACHE,
   DRUPAL_BOOTSTRAP_DATABASE,
   DRUPAL_BOOTSTRAP_VARIABLES,
   DRUPAL_BOOTSTRAP_SESSION,
   DRUPAL_BOOTSTRAP_PAGE_HEADER,
   DRUPAL_BOOTSTRAP_LANGUAGE,
   DRUPAL_BOOTSTRAP_FULL,
  );
?>

The function then defines two more static variables $final_phase and $stored_phase (given an initial value of-1).

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

$new_phase is TRUE by default -therefore the $final_phase isassigned the value of $phase which in this case is BOOTSTAP_FULL which has an integer value of7.

<?php
  if(isset($phase)){
   // Call a phase if it has not beencalled before and is below the requested
    //phase.
   while ($phases &&$phase > $stored_phase &&$final_phase > $stored_phase){
?>

If $phase has a value (it does)the function enters a whileloop. The conditions of the while loop are:
if the $phases array has somethingin it (it currently does)
AND $phase (currently BOOTSTRAP_FULL or 7)
is greater than $stored_phase(currently -1)
AND $final_phase (also currently7)
is greater than $stored_phase(currently -1)
do stuff.

In more general terms, the function is going to keep loopinguntil each bootstrap phase is complete and it reaches the bootstrapphase that was first passed to the function.

<?php
     $current_phase =array_shift($phases);

     

// This function is re-entrant. Onlyupdate the completed phase when the
     // current call actually resulted in a progress in the bootstrapprocess.
      if ( $current_phase > $stored_phase ){
        $stored_phase = $current_phase ;
     }
?>

Once inside the while loop the function 'shiftsoff' the first value of the $phases array and assigns the value to$current_phase.

If you look back, you'll see that the first element of the$phases array was DRUPAL_BOOTSTRAP_CONFIGURATION. Therefore$current_phase gets assigned thatvalue once the array is shifted.

After that, the function then checks if $current_phase is greater than the $stored_phase and if so assigns the value of$current_phase to $stored_phase. This is all about keeping trackof what the current bootstrap phase is and what the phase was.Remember, this function is going to be looping through all thephases. In each loop drupal_bootstrap could be calledagain recursively.

Meat and Potatoes

We arrive at the part that actually starts doing thebootstrapping (starting up) of the individual parts of Drupal.

<?php
switch ($current_phase) {
       case DRUPAL_BOOTSTRAP_CONFIGURATION:
         _drupal_bootstrap_configuration();
         break;

       case

DRUPAL_BOOTSTRAP_PAGE_CACHE :
          _drupal_bootstrap_page_cache ();
         break;

       case

DRUPAL_BOOTSTRAP_DATABASE :
          _drupal_bootstrap_database ();
         break;

       case

DRUPAL_BOOTSTRAP_VARIABLES :
          _drupal_bootstrap_variables ();
         break;

       case

DRUPAL_BOOTSTRAP_SESSION :
         require_once DRUPAL_ROOT . '/' . variable_get ( 'session_inc' , 'includes/session.inc' );
          drupal_session_initialize ();
         break;

       case

DRUPAL_BOOTSTRAP_PAGE_HEADER :
          _drupal_bootstrap_page_header ();
         break;

       case

DRUPAL_BOOTSTRAP_LANGUAGE :
          drupal_language_initialize ();
         break;

       case

DRUPAL_BOOTSTRAP_FULL :
         require_once DRUPAL_ROOT . '/includes/common.inc' ;
          _drupal_bootstrap_full ();
         break;
     }
?>

There is a switch/case statement that checks what the$current_phase is and then executesthe code in the appropriate case.

At this stage in this line by line journey the $current_phase is DRUPAL_BOOTSTRAP_CONFIGURATION so
_drupal_bootstrap_configuration()gets called.

What happens next

Good question, but the answer will have to wait. This is a goodtime to stop for now since each phase in the bootstrap processrequires its own post. Next time we'll take a look at _drupal_bootstrap_configuration.

While you are waiting, and if you are at all curious about theorigins of the bootstrap process, you can check out http://drupal.org/node/18213where drupal_bootstrap was born.