XDebug your IDE

Aug
20
2014

With most languages, when you develop you get the (wonderfully helpful) option of setting breakpoints, stepping through your code, adding watches and inspecting the overall state at any specific point in time. PHP differs in that, being a scripted language hosted in another process (eg Apache) it normally doesn't offer that. Here's how to enable your IDE to do get all the nifty features.

For starters, in case I wasn't clear before - you really need an IDE for PHP for the following; and once you start delving into more complex code you really cannot work without one. I'm currently using PHPStorm , so there are a couple of points where you might need to setup things a bit differently for your IDE of choice - I'll try to point those out.

Getting your server to send debug info

First in getting debug info, is to actually enable your server ( in this guide, Apache ) to send back information required. This is accomplished via a PHP module, called XDebug.

Unfortunately, in CentOS7 at least, XDebug is not made available via yum, so we'll have to compile it. First, we'll install our dependencies for building any PHP module (running as root):


$ yum install php-devel php-pear
$ yum groupinstall "development tools"

With these out of the way, you can now proceed to building the XDebug extension:


$ pecl install xdebug

After some downloading, configuring, making and installing, the last few lines should be similar to the following output:


running: find "/var/tmp/pear-build-rootbLlQ5Q/install-xdebug-2.2.5" | xargs ls -dils
 35095445   0 drwxr-xr-x 3 root root     16 Aug 20 12:50 /var/tmp/pear-build-rootbLlQ5Q/install-xdebug-2.2.5
  2005724   0 drwxr-xr-x 3 root root     18 Aug 20 12:50 /var/tmp/pear-build-rootbLlQ5Q/install-xdebug-2.2.5/usr
 35095446   0 drwxr-xr-x 3 root root     16 Aug 20 12:50 /var/tmp/pear-build-rootbLlQ5Q/install-xdebug-2.2.5/usr/lib64
 73355146   0 drwxr-xr-x 3 root root     20 Aug 20 12:50 /var/tmp/pear-build-rootbLlQ5Q/install-xdebug-2.2.5/usr/lib64/php
100753891   0 drwxr-xr-x 2 root root     22 Aug 20 12:50 /var/tmp/pear-build-rootbLlQ5Q/install-xdebug-2.2.5/usr/lib64/php/modules
100753892 904 -rwxr-xr-x 1 root root 923270 Aug 20 12:50 /var/tmp/pear-build-rootbLlQ5Q/install-xdebug-2.2.5/usr/lib64/php/modules/xdebug.so

Build process completed successfully
Installing '/usr/lib64/php/modules/xdebug.so'
install ok: channel://pecl.php.net/xdebug-2.2.5
configuration option "php_ini" is not set to php.ini location
You should add "zend_extension=xdebug.so" to php.ini

And with that, your extension is built and placed where it should be (note that I've bolded the path where it was installed - you'll need this in the next step). We now need to enable it in PHP, by creating a configuration file for it.


$ vi /etc/php.d/xdebug.ini

And use this as contents for the file:


[xdebug]
zend_extension="/usr/lib64/php/modules/xdebug.so"
xdebug.remote_enable = 1
xdebug.idekey="PHPSTORM"
xdebug.remote_connect_back=1

What we're doing here is:

  • Declare the extension location
  • Enable remote debugging, so it sends data outside localhost
  • Set the IDE key (NOTE: this varies from IDE to IDE)
  • And we set the remote connection to be made to the IP making the request.

Do note the last option again. The way this works, is that WHEN the debugging information is requested, a connection from your server is established to the client requesting the page (default port is 9000).

So let's say your computer has the IP 192.168.1.2 and your web server is at 192.168.1.100 . You would establish a connection from 192.168.1.2 (your computer) to the webserver, requesting the page, and a connection from 192.168.1.100 would be initiated towards your computer.

There are two things that may go wrong here:

  • Assuming the webserver is in the same LAN as your PC, you need to make sure any firewall software on your computer allows incoming connections on port 9000 - otherwise it will be blocked.
  • If you are not on the same LAN, you'll have to forward port 9000 from the internet to your internal IP ( usually from your modem web interface ).
NOTE: The above configuration allows ANYONE to ask for debugging information from your server. There is NO way built in to mitigate that (that I know of).

Restart apache to force PHP to reload its modules (CentOS 7 syntax):


$ systemctl restart httpd.service

If you're using CentOS 6 the syntax will be:


$ /etc/init.d/httpd restart

A visit to any page with a phpinfo() call will verify that the extension is working as expected:

Image removed.

Enabling the debug session on your computer

In the case of your computer, two things need to be done:

  • Your IDE needs to be listening on the port defined for connections. This is done in PHPStorm when in a source file by the phone button (top right) - no setup required.
  • The easiest way to trigger the whole process now, is via a browser extension. I'm using both

In both cases, you need to set the session key to the one you have set in your ini file. In both cases, you just click on the icon on the toolbar to trigger a remote debug session - after that, you can also set breakpoints etc on your IDE.

NOTE: If you set breakpoints before your first page load with XDebug triggered, it won't work because you don't have a connection yet. That is: click on the extension icon, reload - you should see an incoming connection on your IDE. Breakpoints work from that refresh an after. Kinda obvious, but there.

If you have any issues, send a comment my way and I'll see if I can help you out with this. Enjoy!