Drupal 7 Line by Line Part 1 - Introduction

This is the beginning of what I hope will be a series of posts that take you through a Drupal 7 page load line by line.

Introduction

Before we begin, I want to share a story. Its the story of how I accidentally (or rather incidentally) became a Drupal developer.

A few years back I decided to be my own boss. I'd been working as a web application developer for a few years and it was time for me to strike out on my own. One of the first things I needed to do after writing a business plan was to launch my own website - the modern day hanging of a shingle.

I had a basic set of website requirements common to many businesses. I needed a flexible web based system that only needed to be install once and decorated (themed) very infrequently. Once installed it should allow me to enter and organize content via a web interface. I needed to be able to have it up and running in a relatively short period of time and I needed it to cost next to nothing.

Based on my own requirements, I knew I was looking for a modestly featured open source CMS or content management system.

I researched the available open source products that were available at the time. I read feature lists and reviews and eventually narrowed my choices down to Mambo (then soon to be Joomla) and Drupal. I installed both. Then for whatever reason I uninstalled Mambo and kept Drupal 4.4.

With the choice made I got working on a graphic design and the task of decorating/styling/skinning (or what Drupal called theming) my website. The hacker in me didn't bother Googling for answers or reading documentation on how I might theme the site. I just dove into the code.

Here is the code I dove into: index.php - as it was in the days of Drupal 4.4:

<?php
// $Id: index.php,v 1.76 2003/11/25 19:26:20 dries Exp $

include_once "includes/bootstrap.inc";
drupal_page_header();
include_once
"includes/common.inc";

fix_gpc_magic();

menu_build("system");

if (

menu_active_handler_exists()) {
 
menu_execute_active_handler();
}
else {
 
drupal_not_found();
}

drupal_page_footer();

?>

And that's how I became a Drupal developer. I went down the rabbit hole. I began stepping through the code (without a deubugger!) trying to sort out what it was that Drupal was doing so that I could find what I needed to change to make my site look the way I wanted to. By the time I found my answer I had learned more about Drupal than I needed or wanted to know at the time. I was also hooked.

And the rest, as they say, was history.

With the release of Drupal 7 I thought I would repeat the exercise. This time however I will document the experience to share with you. We can learn something new together.

Getting Started: Drupal 7 index.php

Here is index.php - as it is today:

<?php
// $Id: index.php,v 1.99 2009/10/15 14:07:25 dries Exp $

/**
* @file
* The PHP page that serves all page requests on a Drupal installation.
*
* The routines here dispatch control to the appropriate handler, which then
* prints the appropriate page.
*
* All Drupal code is released under the GNU General Public License.
* See COPYRIGHT.txt and LICENSE.txt.
*/

/**
* Root directory of Drupal installation.
*/

define('DRUPAL_ROOT', getcwd());

require_once

DRUPAL_ROOT . '/includes/bootstrap.inc';
drupal_bootstrap(DRUPAL_BOOTSTRAP_FULL);
menu_execute_active_handler();
?>

The first thing you'll notice is that Drupal has a lot more documentation inside the code than it did 6 versions ago. This will make stepping through and explaining the code line by line a little easier (since much of the work is already done). Its worth noting that the code comments are in phpDoc format and are used to generate the code documentation found at http://api.drupal.org/

As you can see in the code comments index.php serves (nearly1) all page requests on your website. In other words, index.php is where code execution begins whether you request http://example.com/home or http://example.com/news/january/headlines or http://example.com/admin/rule/the/world.

Yes. Four (4) lines of code return every single page on your Drupal site! That's pretty amazing. So what's going on here.

A call is made to getcwd() which returns the current working directory which gets assigned to the DRUPAL_ROOT constant.

Basically Drupal is telling itself which directory in the server's file system it is installed and assigning that information to a constant that will be used elsewhere in the code.

Using that constant Drupal then includes the file bootstrap.inc from the includes directory using require_once.

<?php
// $Id: bootstrap.inc,v 1.459 2010/12/30 04:35:00 webchick Exp $
/**
* @file
* Functions that need to be loaded on every Drupal request.
*/
//3000 or so more lines of code
?>

Bootstrap.inc contains roughly 80 functions that "need to be loaded on every Drupal request". As soon as bootstrap.inc gets included 37 new constants get defined.

From those 80 or so functions and 37 or so new constants only the drupal_bootstrap function is called with the value of the DRUPAL_BOOTSTRAP_FULL constant as an argument.

The short version of what is happening in this one function call is Drupal is told to start up (bootstrap) all of its mechanisms required to handle the page request. It loads configuration information, page caching system(s), database(s), session handling, translation system, modules, and everything else you can imagine (and things you might not have imagined) that are required to handle a page request.

The long version of what happens in this one function call is what many follow up posts in this series will be about. You'll have to come back for those.

Finally, the last line in index.php calls the function menu_execute_active_handler(). The short version of what this function does is to act like a telephone operator and direct or route your call to the appropriate function that can answer you.

It takes a look at the path of the requested URL (i.e. the parts after the domain name e.g. news/headlines/december) and figure out which function is responsible for handling requests for that path. Once menu_execute_active_handler() finds the function to call, it calls it. What happens at the point depends entirely on which function was called, but in most cases an html page is sent to the browser.

Once again the long version of what happens is left for another time.

Summary

And there you have it: Four lines of code and only two function calls. All you need to get a page out of Drupal. Sounds easy.

Next time I'll start looking in depth at the bootstrap process in bootstrap.inc and the drupal_bootstrap() function.

If you have any questions, suggestions or corrections just leave a comment. I truly appreciate the feedback.

footnotes

1) I say nearly every page, because install.php, update.php exist and other special or custom parts of your site may be served in a different way.

January 4th 2011 1AM
By: andre

 

Comments

I have read a few other posts

I have read a few other posts trying to explain bootstrap of Drupal. They are not good too, but I will say somehow I learn more, even though this is only the very first post with no insight of bootstrap.inc yet.

For me this post is easier to read and to follow, and help me to form a better picture of how Drupal works.

Thanks. Great work! I will follow this series of post and others of yours.

good

dove an excellent work,keep it up

Thanks for taking the time to do this!

I look forward to reading your posts on this topic. I, too, have thought about digging in from line 1 in index.php and taking it from there. However, I generally get about as far as bootstrap.inc and decide that I really don't have time for this.

I like this approach. To

I like this approach. To start from the beginning of Drupal process - page load. Thank you and keep going with this series.

Thanks for this!

A good friend of mine pointed me to this article. I am usually not one for reading but instead try to tackle things by learning how things work from the inside out. This article as a great way to see the evolution of Drupal and how the nuts and bolts work.

Fantastic job!

Dave

I'd been thinking about doing

I'd been thinking about doing the same thing for Views execution, but I wasn't sure whether it would be helpful for others or not, so it is really interesting to see how you are doing Drupal and how others are finding it helpful. Will be watching as it progresses :)

nice job

THX a lot from france

Rock and Roll!!!

Thanks for documenting this journey! I was trying to understand the bootstrap process to a degree a couple months back and it was too deep for me to plunge all the way down at the time. Having a resource like yours for our fresh D7 will be a terrific resource.

Very interesting!

THX for the article - I am not a developer, just a user of Drupal. This is really interesting to me and I am looking forward to your next post about the depth of Drupal7! :)

Greetings from Germany!

You have my support !

As I'm diving into the Drupal 7 api thanks to "Pro Drupal 7 Development", I also wanted to do EXACTLY what you're doing : understand what happens with index.php and this "mysterious" bootstrap process. So I think I'll be waiting for the coming blog posts of this VERY interesting series to get it right. Very interesting first article. Keep going :)

Great write-up!

Thanks, this is a really nice way to get introduced to how Drupal works. Looking forward to the rest of the series!