Setup xdebug for remote wordpress debugging

Using xdebug is pretty useful for debugging and sometimes understanding existing code. In a typical setup where wordpress in installed remotely on EC2 or any other cloud, it can be little tricky to make remote debugging work with GUI development tools like eclipse. In this article we’ll setup remote debugging for wordpress installed on Ubuntu Linux and eclipse (Mars 4.5.0) installed on Local Mac.

Install xdebug

First install php extension xdebug on remote Linux machine.

$ sudo pecl install xdebug

Add the following line to your /etc/php.ini file

zend_extension=xdebug.so
xdebug.remote_enable=1
xdebug.remote_handler=dbgp
xdebug.remote_mode=req
xdebug.remote_host=127.0.0.1
xdebug.remote_port=9000

Now restart apache server

$ sudo service apache2 restart

Setup ssh tunnel for port 9000

Assuming you are not using port 9000 for any other purpose on server and client machines, run the following command to setup tunnel:

ssh user@remove-machine -R9000:127.0.0.1:9000

This will ensure that when remote xdebug debugger connects to port 9000 on 127.0.0.1, it gets tunneled to port 9000 on client (Eclipse).

Install pdt plugin

Install latest pdt plugin using the instructions mentioned on pdt eclipse page. This is how install new software window will look like:

Setup eclipse project to debug using xdebug

These are the steps to setup eclipse project for debugging:

1. Copy the wordpress root folder from remote machine to local mac. This will make sure wordpress source is same on remote and local machine. We need copy of source code on local machine for debugging. Create a php project in eclipse from existing source (wordpress root folder). The create screen should look like this:
   

   Here blog folder contains wordpress files like wp-config.php, etc.

2. With the php project opened, click on “Run” => “Debug Configurations”. Now select “PHP Web applications” in left pane and click on “launch new configuration” icon on top left.
3. Make sure server tab is selected. Click on new server button and in general setting enter the server details. If you server is dev.infoheap.com then your entries should look like some like this:
   
4. Click next and select XDebug as debugger. Leave the default port as 9000. In case you took a different port earlier for xdebug, you can change it accordingly. Here is how the debugger settings should look like:
   
5. Click finish in debugger settings windows. Now on server tab, select index.php in File box (it should look like /dev1/index.php for a project name dev1). In URL box, uncheck “Auto Generate” and enter / in URL field. The server tab should look something like this:
   
6. Now click on Debugger tab and check “Break at First Line” as shown below. This way when we start debugging, the debugger will be opened on first line itself.
   
7. Now click on debug button to start debugging. If everything works fine, you should debugger getting stopped at first line in index.php as shown below: