Tutorial: Setting up a local Drupal multisite in a Vista/Eclipse PDT environment, by Kipp Elliott Watson

If you benefit from the work I put into this tutorial, consider buying me a beer or a cup of coffee.  I accept bitcoin contributions at 1DBc1wXaaEr3g4eJhc4CEBsvSuQSBduZ3p.  All contributions are appreciated!

Step one: preparing your Vista 64 (or 32) bit environment for setup

The first step is to clean up your Vista 64 (or 32) bit environment so that debris from previous installations of necessary components in a failed setup won't force you to pull your hair out.  This is important because I doubt that you want to become as bald as I am.  This assumes, of course, that you have previously attempted to install components such as WampServer, Xampp, or Xdebug, and like many before you, were never able to find the magic set of configuration settings that would put a warm glow on your face.  If your Vista 64-bit or 32-bit environment happens to be pristine territory then you are good to go to the next step (installing WampServer 2).

Before detailing how your Vista environment can be prepared for a multisite/debugging setup, let's give an overview of the necessary components that you will need to download.  Don't worry.  Be happy that all of this is open source and won't cost you a dime.

There you go.  That's not terribly complicated.  Is it?  Oh, perhaps I should add 7 Zip to this list, although it is really more like a cool unzipping tool rather than a component.  While we're at it, do you have Notepad++ installed in your Vista environment?  If not, get it here.  This is another indispensable tool that is much better than the Notepad application that comes with Vista.  We'll be using it when we open up some pretty sensitive configuration files.

Preparing for a new WampServer installation on top of an earlier WampServer installation unfortunately requires the use of your registry editor, followed by the deletion of the wamp directory and all of its subdirectories.  Before doing this, make sure the WampServer program is not running. Before deleting your wamp directory (at C:\wamp by default), together with all subdirectories, you need to save your accreted content.  Look for this important data in C:\wamp\bin\mysql and its subdirectories, as well as C:\wamp\www\drupal-6.12\sites and its subdirectories.  After you have followed the installation steps in this demonstration project, you can copy your copied files to their original location.  Do not try to mix and match different versions of MySQL related files.

If you have made changes to the following files, make copies of these files for your future reference:
  • C:\WINDOWS\System32\drivers\etc\hosts 
  • C:\wamp\bin\apache\Apache2.2.11\conf\httpd.conf
  • C:\wamp\bin\apache\Apache2.2.11\conf\extra\httpd-vhosts.conf
  • C:\wamp\bin\apache\Apache2.2.11\bin\php.ini
After saving this data you should delete the wamp directory and then proceed to clean the registry of any references to WampServer.  To use the registry editor in Vista, click on the start button and type 'regedit' where you are prompted to 'Start Search'.  This takes you to a window which displays a directory structure which organizes the layout of data entered into the registry.  Highlight 'Computer' and press the [Ctrl][F] key combination to launch a search box.  Type in 'wamp' as a search term.  Delete all instances of a record pertaining to WampServer.  On a healthy installation, there may be 70 such entries or more.  Just grit your teeth and get it done, making sure all the while that the search result is indeed a WampServer related entry.  There are programs like EasyCleaner that claim to do a real rotor rooter job.  I don't think that is really the case.  They don't seem to have a database of any programs, with their related versions and files.  If you think about it, is it realistic that anyone could do this for free?  In the trenches, mano a mano is what it takes.  After all this weed whacking, reboot. Rebooting, which will permanently clear out WampServer related entries, is the prudent thing to do at this point.

Drupal can be removed by simply deleting the subdirectories under C:\wamp\www that were created when Drupal was initially set up.  Typically, something like C:\wamp\www\drupal-6.xx, where xx is a subversion number (as of this writing, the current subversion of Drupal 6 is 12).  As stated above, you should save all your data that resides in C:\wamp\www\sites and its subdirectories.

Eclipse can also be removed by deleting its installation directory, together with its workspace directories.  A good place to install Eclipse is right under the C:\ drive.  Extracting the installation Eclipse files to the root directory automatically creates the C:\eclipse subdirectory.  So look for this directory or do a search for eclipse to determine its location.  Also, to insure a clean platform, you'll want to search for instances of workspace in the subdirectories of the C:\ drive and delete them as well (there could be more than one). 

Remove your Xdebug.dll file.  Well, maybe not.  If you have the right version already, you can leave this one the way it is.  The default location for this project is C:\wamp\bin\php\php5.2.8\ext.  Your Xdebug.dll file will likely have descriptive language in the file name that gives its version and identifies the PHP version that it performs in a stable manner with, such as 'php_xdebug-2.0.4-5.2.8.dll'.  Php_xdebug-2.0.4-5.2.8.dll is indeed the default version for this project, with 5.2.8 referencing the PHP version we are using.

Step two: installing the components

Installing WampServer 2

Installing Drupal 6.12

Installing Eclipse

Installing Xdebug

Step three: setting the configuration files

Do not configure your .htaccess files.  Why?  Because there's no need to.  Just don't get bogged down with them.  Their default values are fine for purposes of this demonstration project.  You will need to configure your hosts, http.conf, httpd-vhosts.conf and php.ini files, however.

Configuring your Vista hosts file

Configuring httpd.conf

Configuring httpd-vhosts.conf

Configuring php.ini 

Step four: setting up a PDT Eclipse project

If you have seen this image in your browser, you are ready for this final step:

If you have not yet conjured up this image in your browser, more carefully go through the first three steps here again.  Or you can put your two cents in the comment box below and blame me for everything else while you're at it.  I don't care.  Hey, if you do get this far, let me know that too!  It would put a smile on my face.

OK.  Ready?  Fire up your PDT Eclipse.  You'll be asked for your workbench location.  I recommend 'C:\wamp\bin\apache\Apache2.2.11\htdocs'.  Use the [Browse] button to minimize typos here.  Eclipse partitions workbench and local resources, presumably to discourage overlapping projects.

Click [OK] and proceed to this introductory screen:

This is where you click [File], then [New], then [Project] to come up with this wizard:

Naturally, we open up the PHP item, select 'PHP Project' and click [Next >]

We are now ready to create a new PHP Project.

Actually, not.  We don't have a Drupal website set up yet!  Let's set one up right now and come back to this screen.  Have you gotten to the point where your browser displays this?

Great!  Now let's go back to the new PHP project wizard.  

When you are in the new PHP project wizard enter 'Multisite' as the Project name.  The default for the project location is 'Create new project in workspace.  Change this to 'Create project from existing source' and enter 'C:\wamp\www\drupal-6.12' for the location.  All other options in this wizard are fine with default settings, so click on [Finish].

The next set of configuration settings that we deal with are Eclipse's Preferences.

We pull down Window from Eclipse's main toolbar (at the very top) and then we select preferences, displaying something like this:

We will be concerned here with settings for PHP Servers and PHP Executables.  Here is the display for PHP Servers:

If a Default PHP Web Server entry is already entered, select it to highlight the [Edit] button, then edit the entry so it looks like this:

Technically, the document root of this server is C:\wamp\www\drupal-6.12 (remember we set this in httpd.conf?), but we're going to play a little fast and loose with this setting in Eclipse.  We will set it to 'http:/' because we want to capitalize on Drupal's ability to find the right 'settings.php' file in a multisite cluster of subdirectories just off of 'C:\wamp\www\drupal-6.12\sites'. 

In other words, when we want to debug 'www.mysite1.com', we need Eclipse's Web Server configuration to point to 'http:\\www.mysite1.com' as the browser's entry point for debugging purposes.  

Thus, when Drupal is sent a request for 'http:\\www.mysite1.com' its initial setup routines will find the 'settings.php' file found at 'C:\wamp\www\drupal-6.12\sites\www.mysite1.com\settings.php'.  

Because of this artificial Server setting for the document root, we will not need to utilize any path mapping, so we can leave the 'Path Mapping' tab empty.  Click [OK] here so we can move on to editing the entries for Eclipse's main PHP executable settings at [Windows][Preferences][PHP Executables].

Note that there are four settings in the Edit PHP Executable window.  First we give it a name, such as PHP Executable.  Then we give the location of 'php.exe'.  It makes sense for PDT Eclipse to be told at some point where PHP's main engine is hanging out, doesn't it?  

The next entry 'PHP ini file (optional):' is the key configuration entry for this entire project!  This is where most people fall short of their dream to step through Drupal's orchestral movements one step at a time.  This is not an optional setting, as Eclipse's developers might have you believe.  Note also that we do not enter 'C:\wamp\bin\php\php5.2.8\php.ini'.  We enter the same location that is given by phpinfo.php's 'Loaded Configuration File', namely 'C:\wamp\bin\apache\Apache2.2.11\bin\php.ini'.

When you arrive at the Zend and Xdebug choices for PHP debugger, we'll select XDebug (which is usually spelled Xdebug by its creators).

Now click [OK].  We are done with Eclipse's preferences.  For some quirky reason not understood by me, you must exit Eclipse and start it up again for these preferences to take effect.  This is just one of those things that tries the patience of many people, so be assured you're not alone.

Next, and finally, we will deal with a configuration window for locking and loading the debugger.  In the Project Window's displayed directory, look for the file 'index.php'.  Everytime Drupal is run, this is the file that begins the whole browser experience.  The first line we could possibly debug is at the beginning of this file.  Left-click (or right-click, depending on your mouse's settings) this file to bring up a long list of options and look for [Debug As].  Look for further options under this menu item and select [Debug Configurations ...].

This will bring up your Debug Configurations Window.

Note that there are seven settings on this page we need to address.  We need to give a name for our debugging configuration set of settings.  'Multisite' is used as a name here to draw attention to the fact we only need one set of debugging configuration settings.  Think about this for a minute.  Multisite Drupal basically is a collection of different websites, all sharing a common core of Drupal modules and themes.  Usually when an IDE, such as Eclipse, is used for the development and debugging of projects, the overlapping of project resources is structurally discouraged.  Otherwise the costs of management can get unwieldy.

We can totally avoid this restriction on overlapping projects by controlling the entry point of our browser.  We set two key settings in the URL panel.  We unclick 'Auto Generate' and we enter the alias for '' (localhost's IP) that we set in Vista's 'hosts' file in the second text box that follows 'URL:'.  Remember that we set three of these aliases (other than 'localhost') in our 'hosts' file?  'Www.mysite1.com', 'www.mysite2.com' and 'www.mysite3.com' ... all pointing at IP ''.  If we want to debug 'www.mysite1.com', we enter 'www.mysite1.com' in this second text box.  Similarly, we enter 'www.mysite2.com' if we want to debug 'www.mysite2.com' and we enter 'www.mysite3.com' if we want to debug 'www.mysite3.com'.  That's pretty straightforward, isn't it?

The proper entry for 'File' here is /Multisite/index.php.  Using the [Browse] button helps to avoid typos.

Hit [Apply], then [Debug].

If everything goes just swell, you'll see a browser pop up and not display anything.  Don't get nervous.  This is just one of the little impish things that Eclipse does.  Minimize the browser and consider yourself home free if you see this image:

Click [Yes] and you will definitely get a whole new perspective on things.  Things like this perspective on the first active line of code in any Drupal website:

Every variable you can think of is displayed in the Variables Window!  How cool is that?  Do you think you could learn a bit about Drupal by watching how these variables change from one line of code to the next?

The green, red, yellow and blue arrows here point to the 'resume', 'stop', 'step into' and 'step over' icons.  These are your navigational tools that allow you to inspect every line at which you might care to place a break point.  Clicking on the 'step into' icon will, for example, immediately bring you to line 13 of file 'bootstrap.inc', which is called by the first active line in 'index.php'

Because Eclipse is a real powerful IDE and debugger, you are not limited to going through thousands of lines just to get to a particular point of interest.  Use Eclipse's help features to learn about hit points and conditional breakpoints.  You will also need to become familiar with Eclipse's facilities for using content types.  These allow you to use files with extensions such as .module, .theme, .inc, .install, .engine and .test as if they were files with a .php extension.  For more info on this, go here.

Happy debugging days ahead!