How to debug PHP applications

Avoiding all the fuss and trying to debug first

There is a shortcut to all of the configuration and installation for your own debug environment. I have created a fully pre-configured Linux VirtualBox machine that you can simply download, install and try debugging without any hassle at all. If you like the debug abilities you can continue with the rest of the article and set it up on your own machine.

The VirtalBox machine can be downloaded here: VirtualBox LAMP machine.

All you need to do to try the machine out is download and install VirtualBox and import the machine. If you like it, you can continue with the rest of the article.

The actual thing

The fact that you are looking into debugging PHP applications tells me you are on the path to mastery of PHP programming language and software development in general. Not to delay you any further I whish to present to you XDebug. XDebug coupled with a development environment and a little bit of trickery can give you a very sophisticated debugging environment allowing you even the luxury of debuggin remote sites.

I use this setup daily on my customers sites and the only thing I can comment about it is that it saved me countless hours. The tutorial video itself focuses on debugging TYPO3 CMS applications using Eclipse, XDebug and SSHFS.

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 highschool 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 th

  1. A live site on my server in Frankfurt fails in some mistical manner.
  2. I am notified of the failure and fire up Eclipse immediately.
  3. I fire up the XDebug extension on the server.
  4. My Eclipse installation already contains prepared projects and debug sessions so I just fire up the appropriate one.
  5. 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.
  6. 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. There is very little difference between setting XDebug environment under Windows as opposed to setting it up under Linux. Just the standard hassle of different paths and a little bit more hassle to get the Windows version of SSHFS working and you are all setup and ready to go.

Installing Eclipse

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.

Installing XDebug

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_log = /tmp/xdebug.log

The xdebug.remote_host="" 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 aswell. You can find out about all XDebug settings on their 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.

Installing SSHFS

NOTE: If you are less fortunate and don't have Linux OS there is probably some shareware/freeware utility for your OS of choice that would allow you to mount SSH account to your machine. Just google 'ssh mount yourOperatingSystem'. Ries of #typo3 just mentioned to me the OSX solution:

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 filesystem 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 /existing/path/on/the/local/machine/ -o gid=44,uid=1012,reconnect -p 12345

The part should be pretty self explanatory. The format is user@ip:/path/you/want/to/mount.

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 remaping 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:

# mount 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.

Symlinks from hell

Yeah... I lost a bunch of time on this one so remember me in your prayers. If the source code of your website/cms contains any symbolic links, such as TYPO3 does, the debugger gets all messed up and can't find the correct source file. So before you start debugging you might need to remove all symbolic links and copy the actual folders in their place. If you do end up doing this step remember to refresh the project in Eclipse.

Your thoughts

martin, 23-06-12 01:36
OK I think Im giving up on this ...

I folowed you instuctions but try as i might I can not get my remote server to list my web dir... I keep getting ls: reading directory .: Permission denied. Even though it list all others before it. before I quit any sugestions???
martin, 22-06-12 11:19
Hi there

I know this blog is a little old, but its still relevant to a PHP beginner like me.

Im having a problem with what machine your referring to when installing sshfs (local or remote).

Also how do I install fuse, I've tried installing fuse-utils but I still get no response from listing the installed modules

Many thanks
Alfonso, 07-01-11 15:57
Hi! Can you please write me so we can keep in touch? I can debug a single php file (useless), but not the whole system as you do (usefull). Thanks a lot

Add comment

* - required field