Debugging is the art of resolving defects in software or hardware. When developing for Drupal, you may want to see what is going on in your code while it executes. There are a number of ways to achieve this.

Drupal logs errors to the Watchdog log (/admin/reports/dblog) and your webserver will log any further errors to its error log. (For example, on debian based systems, this would likely be at /var/log/apache2/error.log).

Based on finding errors in Watchdog, or your webserver error log, you may then wish to investigate these problems further by looking at the state of code as it runs.

Some of the modules you might want to look into are as follows:

If you’re debugging Drupal 6 or 7 code the devel  module is often sufficient, but with the change to Symfony in Drupal 8 the code base is much more complex.

This is where using a step debugging tool like XDebug can provide you with a lot of help for watching your code execute line by line to understand where you may have issues.

This tutorial will cover configuring and XDebug for your Vagrant virtual machine. Building a virtual machine with Vagrant is beyond the scope of this tutorial. Read Getting Started with Vagrant for more information.

Your vagrant VM should be provisioned with PHP, XDebug, and a webserver of some kind.

Getting started

First of all, you will need to know which IP address your VM has as we will use this when configuring XDebug.

SSH in to your VM, and open up your XDebug config.

A quick php -i | grep xdebug.ini  in your terminal should show you where the file is you need to edit.

Add the following to XDebug config, substituting  xdebug.remote_host for your VM’s IP:

After setting this configuration restart your webserver or if you’re running php-fpm  then restart that to pick up your new XDebug config.

You can verify it’s set up correctly by looking at the output from php -i | grep xdebug to see all of the XDebug configuration.


Install the php-debug package for atom like so:

apm install php-debug
Now restart atom and let’s configure the php-debug plugin.

Open  Atom > Preferences > Packages  and search for php-debug and click the Settings button.

There are two settings we need to set in php-debug configuration, namely the Server Port and Path Maps so scroll down a little…

Set the Server Port to 9999 (or whichever port you configured Xdebug to use, i.e. xdebug.remote_port.)

To set the Path Maps section, you need to set the path to your files on your VM and then the path on your host system.

For example, on my VM, my Drupal project is at /var/www/drupal.

On my host system (OSX in this case) my project is at /Users/willwh/Sites/drupal.

So, I set my Path Map as follows:


With all of this configuration done it’s now time to set some breakpoints and start debugging!

Click the “PHP Debug” button in the bottom left menu to open the Debug dialogue.

Open up a file from your Drupal project in atom; let’s use index.php  as an example.

If you click just to the right of a line number in Atom you should see a little green dot, which is a breakpoint, and this is where code execution will be halted when reached.

You can also set breakpoints on a line with a right click and then from there go to the context menu and select PHP-Debug -> Toggle Breakpoint.

After setting this breakpoint navigate to your Drupal site in a browser and execution should halt on your breakpoint.

You can now step through your codebase using the options in the PHP Debug dialogue in atom!

There are keyboard shortcuts for php-debug which you can view in atom’s settings.

Examining code state

When your code has stopped on a breakpoint the “Content” pane in the php-debug drawer in atom will show all of the loaded variables. Each object will have an arrow next to it showing that it can be expanded.

Using Step over,  Step in,  Step out will allow you to step through your code as it executes and you can see the Context changing in the pane below.

I want to briefly mention the “Continue” button; this tells XDebug to allow your code to continue and it will stop on the next breakpoint you have set. If you only have one breakpoint set clicking continue would allow your code to fully execute without stopping.

Happy debugging!