Xdebug + Scotchbox Vagrant + PHPStorm in Three Steps

I come from a .NET background where I was spoiled by the ease of use and integration of Visual Studio. Recently much of my development work has moved to the open source and the world of Drupal 8 where I have gotten by until recently with Sublime Text and Atom. Since I have started writing custom modules, I needed a way to effectively debug my code and I had heard good things about the PHP debugger Xdebug. Unfortunately it can be a little tricky to setup, so I have outlined the basic steps I needed to go through using my favorite Vagrant environment Scotchbox. If you are unfamiliar with Scotchbox, check out my earlier posts Scotchbox Vagrant LAMP Stack and Drupal Development Environment in less than 10 Minutes

Step 1 – Installing Xdebug for Scotchbox Vagrant

Scotchbox is a clean Vagrant environment for LAMP development without all the frills of more comprehensive setups, therefore it does not come with Xdebug out of the box. Thankfully though, installing Xdebug is straight forward, especially with the help of Rocinante’s Tech Stuff, who outlines the steps necessary to get Xdebug up and running quickly:

SSH in to your Scotchbox Vagrant instance and run the following to get the latest package lists:

sudo apt-get update

Next run the following commands to install Xdebug:

sudo apt-get install php5-xdebug sudo service apache2 restart

Edit php.ini:

sudo nano /etc/php5/apache2/php.ini

Add the following lines:

[xdebug] zend_extension="/usr/lib/php5/20131226/xdebug.so" xdebug.remote_enable=on xdebug.remote_connect_back=on xdebug.remote_host=192.168.33.10

Step 2 – Configuring PHPStorm

There are several different ways to setup PHPStorm and Xdebug with Vagrant. For simplicity we are going to use remote debug with a Chrome plugin called Xdebug Helper. First let’s setup PHPStorm.

• Open your PHPStorm project and then go to Run -> Edit Configurations
• Click + and select “PHP Remote Debug”
• Enter a name for the configuration and then select … next to servers in order to add a new server configuration
• In the Servers window click + and provide name and host of your server (e.g. vagrant.local)
• Select “Use Path Settings” and provide the absolute path to your project (usually /var/www/projectname)
• Click Apply and then click OK to save server settings
• Enter “PHPSTORM” for Ide key (session id) and then click OK

If you have set everything up correctly you can verify your server and debugging configuration is correct by selecting run -> Web Server Debug Validation. Enter the vagrant URL where your project is located (e.g. vagrant.local) and click Validate. If you are successful you should see output similar to the screenshot below.

If you receive a connection error, verify your VM is up and running and recheck your settings. If you are using a different type of Vagrant setup from Scotchbox, check out this excellent tutorial over at SitePoint.

Step 3 – Install and Configure Xdebug Helper

Download Xdebug Helper from the Chrome store. Go to Xdebug Helper options and select PhpStorm for IDE Key. At this point everything should be up and running. Next you can test by inserting a breakpoint in your code.

• Add a breakpoint to a section of your PHP code. I used the default scotchbox index.php and placed a breakpoint before the mysql checks.
• Select Run -> Debug ‘Scotchbox’ or click the small green bug icon on the top right hand corner of the IDE
• Browse to you project page (e.g. vagrant.local) and select ‘Debug’ from the Xdebug Helper icon
• Refresh your page and your breakpoint should be hit in the IDE.

You can use the various debug options in PHPStorm to step in and out of code sections. For more information on debugging within PHPStorm visit JetBrain’s Debugging PHP Applications documentation. That’s it, now you’re up and running debugging your applications with Scotchbox and PHPStorm.