How did it even come to a point where I needed this? Well, owning a dedicated Debian box in Frankfurt with some 50 websites that tend to have problems from time to time led me to a painful conclusion that debugging using echo statements is better left for high school lessons. If I was left without my debugging setup today I would probably feel like trying to code an operating system in assembly.
So how does a practical scenario of what you will learn to do look like? Well it goes something like this:
- A live site on my server in Frankfurt fails in some mystical manner.
- I am notified of the failure and fire up Eclipse immediately.
- I fire up the XDebug extension on the server.
- My Eclipse installation already contains prepared projects and debug sessions so I just fire up the appropriate one.
- Withing up to two minutes I am stepping through the code of the offended website and usually within a few minutes the bug is squashed.
- Turn off the XDebug extension and all is back to normal.
But don't be mistaken, this setup is not only for live sites. I absolutely do use it while developing PHP applications. The reason I used this example is to show you the sheer power it possesses in critical and urgent situations when you have that client banging on your door to get his site working.
Instructions featured in this article are Linux oriented for brevity. In order to get the instructions for Windows you will need to check out the original tutorial. A link to the original tutorial is found in the signature.
The first step in our journey is to install Eclipse IDE with PDT (PHP Development Tools). You should be able to fetch the latest version of Eclipse PDT for your operating system at the Eclipse downloads section. The installation procedure on my Debian box was trivial: download, extract and run. The only issue I run into was not being able to run Eclipse with PDT in a stable manner with anything other than Sun JRE. So if you get any weird errors that might be your culprit.
The next thing is adding the debugging ability to your PHP Apache extension. Under Debian box this turned out to be pretty trivial:
# aptitude install php5-xdebug
However, you also need to set some things in php.ini:
xdebug.remote_enable = 1
xdebug.remote_host = "hostname.dyndns.org"
xdebug.remote_port = 9000
xdebug.remote_handler = "dbgp"
xdebug.remote_log = /tmp/xdebug.log
xdebug.var_display_max_depth = 10
xdebug.var_display_max_data = 10240
xdebug.auto_trace = 1
xdebug.trace_output_dir = / tmp
zend_extension = / usr / lib / php5 / 20060613 + lfs / xdebug.so
The xdebug.remote_host = "hostname.dyndns.org" points to my home desktop which enables me to connect remote to the xdebug session within php from my desktop machine. If you do not have dyndns domain for your home machine you can enter your current IP as well. You can find out about all XDebug settings on the XDebug documentation page. Once you install XDebug extension you should load phpinfo () and check out if the output contains something like this near the top:
This program makes use of the Zend Scripting Language Engine: Zend Engine v2.2.0, Copyright (c) 1998-2008 Zend Technologies with Xdebug v2.0.3, Copyright (c) 2002-2007, by Derick Rethans
If it does you succeeded in installing XDebug. We have only one more thing to install and that is SSHFS.
Why SSHFS? Well … while you are debugging your remote site Eclipse needs to have access to it's source files since that is the only way it can step you through the code while it is being executed. Now, since the site is on a remote server you can either copy it to your machine or somehow make it so that Eclipse can access it via internet. If you copy the sources to your machine you will loose the ability to modify the running site since you will only be modifying the copy. So the only option that we can accept is to somehow gain access to the sources over the internet. This is where SSHFS comes to play. SSHFS will enable you to mount your remote ssh account to your local file system and access it as if though it was on your own machine.
Again, under linux, it turns out to be pretty trivial:
# aptitude install sshfs
However there is a dependency of sshfs that aptitude did not warn me off. It is fuse kernel module. In order to check if you have it installed try out the following:
# lsmod | grep fuse
You should see something like:
fuse 43676 3
If you get something like this you have the module inserted in the kernel and you are ready to use SSHFS to mount your remote ssh account.
To mount the ssh account you should do the following:
# sshfs vlatko @ xxx.xxx.xxx.xxx:/var/www/ / existing / path / on / the / local / machine / -o gid = 44, uid = 1012, reconnect -p 12345
(there are no spaces around @)
The vlatko @ xxx.xxx.xxx.xxx : / var / www / (there are no spaces around @) part should be pretty self explanatory. The format is user @ ip: / path / you / want / to / mount. (there are no spaces around @)
The second parameter is simply the path on your local machine where you want the remote path mounted. This path must exist and should be an empty folder.
The third parameter simply specifies the ssh port which is usually changed from the default 22 to something more obscure on most web hosts.
The part after the -o in my case is dealing with remapping the remote userid and groupid to local userid and group id. Obviously you want to mount these to the user and group id of the user on your local machine.
After everything is setup properly and working you should get something like this when executing:
vlatko @ xxx.xxx.xxx.xxx:/var/www/ on / home / vlatko / mounts / abraham type fuse.sshfs (rw, nosuid, nodev, max_read = 65536, user = vlatko)
So once you got this setup you need to mount the folder in which your web site source code is located to a folder on your local machine. Let's assume that your website is under / var / www / mysite / and you mounted / var / www / locally under / home / myself / mounts / myserver /. So under / home / myself / mounts / myserver / you will have all the sites on your server including / var / www / mysite / which will be located on your local machine under / home / myself / mounts / myserver / mysite.
Using Eclipse to make all these dance together
Once all the needed parts are installed and running we need to make them work together. This might be a little tricky to get running the first time, but once you make it you won't go back. I promise.
Run your Eclipse IDE and start a new PHP project. (File -> New -> Project and then select PHP -> PHP Project. After you enter the name you need to select 'Create project from existing source' and select the / home / myself / mounts / myserver / mysite. After the project builds you are left with the last step.
Creating the debug configuration
Debug configurations are created under Run -> Debug configurations.
You need right click PHP Web Page and select New. Fill in the name and select XDebug under Server Debugger. For PHP Server you need to choose New and enter a name and the url that loads your website. Under File select the file that loads your home page which is usually an index.php in the root of your website. I always uncheck 'Break at first line' and 'Auto generate'. Especially 'auto generate' tends to generate urls that are not correct so after I uncheck it I also delete the url it generated so that it points to the home page on your website.
This should be it. Press Debug and you should get a Debug perspective opened along with a running debug session. You can toggle breakpoints by double clicking the blue vertical line left of your source code. I usually start by opening the index.php of my site and setting the break point on the first expression in the source just to test if the debugger works and then work my way from there.
My original tutorial also contains a link to a VirtualBox LAMP Stack which contains all of the needed software preconfigured and ready for testing. With the stack all you need to do is download and install it and you are ready to test how it is to debug PHP applications with XDebug and Eclipse.