Recently we were passed a large existing project developed in Drupal 5, and asked to make modifications to it pending a full upgrade of the site to Drupal 7. Given the age of the code and the fact that Drupal 5 has been unsupported for some time, none of the development teams machines had the necessary tools to work on it. What we needed was effectively an old machine with an old copy of Ubuntu to develop it on.

Vagrant

This is where Vagrant comes in - it's a neat wrapper around VirtualBox, that builds and configures a Virtual Machine instance in just a few commands.

Thanks to De Jonghe Nico for this prepared Vagrant configuration for a PHP 5.2 development box. It's based on Ubuntu 8.04 LTS, which is a really old release but at the same time perfect for our purposes as it's from around the Drupal 5 era:

http://www.dejonghenico.be/unix/drupal-6x-php-52-vagrant-devbox

We set this up to be rooted at /var/www/vagrant on the local machine, as /var/www is essentially where the rest of the development projects live, so it kept it well organised.

Two port forwards need to be set up, one for accessing SSH, the other for the web server. In the Vagrantfile configuration file, ensure these lines exist in the relevant place:

config.vm.forward_port 22, 2222
config.vm.forward_port 80, 8080

This sets up SSH so that it can be accessed from localhost:2222, and the Web Server so it can be accessed from http://localhost:8080/. Of course, choose other unused ports if these choices are already for use for something else on your development machine (one of our developers was already using 8080 so they chose port 1337).

Apache2 and Drupal

Once we had the instance up, we configured an Apache2 web server inside, and placed a copy of Drupal 5 core into /var/www/vagrant locally, as this folder appears as /vagrant inside the Vagrant instance. This allows us to work on the files locally, and have them pop up right away on the Vagrant Web Server as though we were developing it directly on the machine.

The "DocumentRoot" for the Apache2 server is then set to /vagrant inside the configuration.

XDebug

Once we had the Drupal 5 site working and available from http://localhost:8080/, we of course wanted to be able debug it. As the Web Server is running inside Vagrant, which is a self-contained box that uses NAT to communicate with the outside world, this poses problems for the back connection XDebug normally performs - XDebug will try to connect back to the IP that initiated the HTTP request that triggered the debug session, but this is effectively always the local Vagrant machines IP due to the Port Forwarding. So basically we need to override this behaviour to force all of the debug requests to be sent to the development box, where the IDE is listening.

We do that by adding the following config to the end of /etc/php5/conf.d/xdebug.ini inside the Vagrant box (this applies to Ubuntu, but do adjust this if the path is different for your platform)

xdebug.remote_enable=1
xdebug.remote_host=mybox
xdebug.remote_port=9000

Change mybox for the hostname or IP of your development machine. Note that this needs to be a fixed address, so if your box is given a dynamic IP via DHCP you may need to get a static mapping added to ensure this works.

Don't forget to restart Apache after changing this file so it picks up the new configuration

Server paths

So now, if you start a debug session in PhpStorm, you should see the 'Connected' message in the debug pane every time a request is made. However, no breakpoints will be hit. Why? By default, the file paths that come through to the Debugger will be /vagrant/something.php, which of course is unlikely to match where the file 'something.php' actually is on your local box. PhpStorm allows you to fix this however. If you open the "Run/Debug configurations" window for your project, and select the ellipsis (...) next to "Server", there's a check box for "Use path mappings". From here, you can map where the file is in the Vagrant instance to where it actually is in your local file system:

Once this is configured, start a debug session, and you should find that any breakpoints in your code are now hit as expected.

Conclusion

It's quite a lot of set up to get this to work, but once done, it makes development of a site inside a Vagrant instance as easy as developing locally.