xDebug Remote Debugging With WordPress and phpStorm

I’ve been using phpStorm to do local debugging of my WordPress app on a VVV box for a few years now.   This week I have been running into some challenges with the MySLP SaaS service and while the app works fine on my local setup it is not behaving the same way on the staging deployment out in the cloud.   I need to know why and I’m tired of hard-hacking the code on the staging site with error logs.    Live debugging with code tracing and memory stack access is a far better way to go.

phpStorm has this and I need it.  The problem is my code is running in the cloud and my codebase is local on my laptop.   How to connect to two?    Here are my hints from the deployment.

Local box running MacOS Sierra with the latest 2016.3 phpStorm and a Firefox browser.  Remove box running Ubuntu 16.04 on AWS.    This assumes you have some clue about system admin and local system configuration.

The Setup


apt-get install php-xdebug

Edit the php ini file for xdebug that was installed.   I’m on PHP 7 so it is in my PHP 7 config dir under /etc/php/7.0/mods-available/xdebug.ini.

Add some lines to tell xdebug to allow remote connections to your soon-to-be-listening IDE (leave the first line to the zend_extension for xdebug in place):

xdebug.remote_host=<your local box’s public IP>

Restart your web server (nginx in my case) and if you are using FPM or another PHP accelerator restart that as well.

On Your Local Router

You’ll need to make sure that when your web server sends along the “let me connect to port 9000” your firewall knows which laptop to send it to.    Configure your firewall to port forward port 9000 to local port 9000 on the local IP of your laptop.   This is usually some 192.168 address NOT the public IP you used above.

In phpStorm

Setup your server.   In phpStorm go to the Preferences Menu then look for servers under the PHP entry.

Add  a name for your server.  Set the public URL to the site you are connecting to and the port.

Use path mappings.

Map the SERVER absolute paths to your current project files.  For example, my project file/directory ~/SLP/wp-content/plugins is mapped to the /server/websites/myslp-dashboard-beta/wp-content/plugins directory.

Save that.

Go to the Run / Debug menu and add a new configuration.

Give the config a name and attach it to the server you just setup.

Make sure you set the IDE session key to the same value you put in your xdebug config file.

Firefox Extension

Go to Firefox add ons and install theeasiestxdebug extension.


Using It

Start phpStorm and open the debugger with Run | Debug | <your new debug config> and in the code of your project pick a module you want to debug and set a debug break point.

Go to your site in your browser.

Click the new xdebug icon  the Firefox plugin installed in your toolbar to send a message to your web server “start a debug session”.  Load your page and your phpStorm debugger should catch the debug message being sent from your server for that page load.

This xdebug page will help you visualize the communication process and learn about the configuration of PHP and xdebug.




Leave a Reply