XDebug and PHPEclipse


This guide will focus on using the XDebug Debugger with PHPEclipse. It will cover the XDebug config file for the server (apache), setting up a XDebug profile in PHPEclipse and starting your debug session. The installation of XDebug on the server is outside of the scope of this document. Please refer to the XDebug website for guidance on installing XDebug on your server. This guide was written using CentOs 5 as it's example server and also using the documentation done for PHPEclipse. Your system may be different. If so please open a ticket and mention the change. This guide will be updated to reflect changes for different platforms. This guide assumes that you already know the basics of creating projects and PHP files using PHPEclipse.
Special Note:
Before you begin insure that you have only the XDebug plugin from the PHPEclipse update site installed. You can go to Help->Software Updates -> Manage Configuration to check for DBG plugin. If it is installed, just disable it. The two debugging tools not working well together is a known issue in the 1.2.0 release of PHPEclipse.

Special Note 2:
As of PHPEclipse 1.2.x trying to debug an RSE project will not work. The src needs to be on local disk, or a mapped nfs mount/ smb directory.

Project Paths

Getting the paths to work is a big issue with Eclipse and Debugging. I am going to try to make this as clear as possible. First we have our apache website path. Our apache config may look something like this

<VirtualHost *:80>
    ServerAdmin ed_mann@dont_spam_me.ok
    DocumentRoot /home/ed_mann/dev30
    ErrorLog logs/dev30-error.log
    CustomLog logs/dev30-access.log common

From above we can find that our Remote Src path is the DocumentRoot which is set to /home/ed_mann/dev30.
Remote Path = /home/ed_mann/dev30 You will need to replace that Remote Path with the path you get from your Apache conf file, or your virtual host configuration.

If you are using an Alias in your apache conf

 Alias /project "/var/www/workspace/project/"

you will need to use /project as your Remote Path.

Now on our local machine where we are running Eclipse our workspace is in
and the project is called dev30
So our total local path would be
local path = /home/ed_mann/workspace/dev30

Please change "local path" to your workspace and project name path. We will be using this information later, so keep it in mind or write it down.
Notice how our apache path does not have workspace, but our local path does. That is ok. The server that is hosting the files stores it in the ed_mann directory, but you can use a nfs/smb/sftp(fuse) export to mount the files into /home/ed_mann/workspace. So if the paths are not the same it's ok. Eclipse only needs to know where on each end is the source files.

XDebug config

Note: When installing precompiled XDebug binaries (under Windows for example), ensure that the PHP and XDebug build versions are compatible. XDebug needs to be built specifically for the PHP version in use, so if they don't match, you may well find yourself chasing your own tail for some time. This tends not to be so much of an issue if you're building your own XDebug libraries or are using a platform which supports package management.

Your server may have a /etc/php.d directory with extra configuration options in it for php. If not you will need to add the following code to your php.ini file. If you have a php.d directory create a new file in that directory named xdebug.ini and add the following code:


Note you will need to change the remote_host to the ip address of your local machine. If your apache server is on your local machine you can change this to or localhost. Also insure that you use the zend_extension and remove any other mention of extension from the file.
Once the code is added restart Apache. Create a php file in your document root for the website you can call it whatever you want we will use info.php in this document. Add the following code to the info.php file.


When you have done this, now with your browser type in the url address to get to this page. Example http://localhost/info.php
Look for the section that resembles the image below
xdebug info ss
If you do not see XDebug in the section like above check your settings, make any needed changes and restart apache.

Test Project

Once you have XDebug installed into php on the server you can now configure XDebug in Eclipse. Start Eclipse and activate the PHPEclipse perspective if it is not already. You will need to import a project to use from your webserver or create a new project on the web server. Configuring the web server for projects is out of the scope for this document that exercise is left up to the reader. Once you have your project established create a new file called xdebug.php.
Starting of simple we will just add the following to the xdebug.php file.

 print("XDebug Test");

Now with your browser connect to the page with your browser Example: http://localhost/My_Project/xdebug.php.
Once you have done this and verified that the text appears you are ready to configure a XDebug Profile and our debug script.

Debugging Script

You should have verified your environment is setup to debug using the steps above. Now we need to write some code that will allow us to test debugging our php script. In our xdebug.php file we are going to remove the print("XDebug Test"); statement with a little loop that will allow us to step into the code.

for ($i =1; $i <= 10; $i++){
  print (" we are at ". $i. "<br />");

On the line that starts our for loop toggle a breakpoint. You can do this by right-clicking in the gutter and selecting Toggle Breakpoint
debug toggle break point

You should see a blue dot appear to signify where the breakpoint is. Now change to the Debug Perspective. Window->Open Perspective -> Debug
Now we can configure our XDebug Debug Profile. We will only need to do this once per project.

Local Debug

Specifying the PHP Interpreter Path

To begin, we must specify the PHP Interpreter Path. This may differ depending on your system. For Windows based systems, this is a path to a file called php.exe. For Linux systems, this is a path to a file simply called php. For Linux systems, this is often in /usr/bin/php. To specify the PHP Interpreter, select Preferences from the Window drop down menu. Open up the PHPEclipse selection and click on XDebug. In the settings pane on the right that appears, enter your debug port and the path to your PHP interpreter. The default debug port for XDebug is 9000, but your system may be setup differently. To verify that 9000 is the correct port, find a way to access your phpinfo() page and check the value of xdebug.remote_port. The value of xdebug.remote_port should match the debug port value.
xdebug setup
When you have entered the appropriate values, click on the OK button.

XDebug Debug Profile

Now that we have configured XDebug, we need to create a debug configuration. This will tell Eclipse how to start the debugger for your project. To do this, select 'Debug Configurations...' from the Run drop down menu. You will be presented with a list of items which you can debug. Double click on the entry titled 'PHP XDebug Script'. This will create a new configuration and allow you to specify the necessary options. You can provide a name for your debug configuration, and then you must specify the filename which should be executed for debugging purposes. In this case, the filename is index.php.

You should get the Debug Dialog Window. We will create a new PHP XDebug Remote Script by double clicking on the PHP XDebug Remote Script list entry.This will create a new configuration and allow you to specify the necessary options. You can provide a name for your debug configuration, and then you must specify the Ide Identification String. You can select anything you want for this string. It is recommended to keep it short and memorable. Ensure that you remember this value for later. In our example, we will use the string firstproject.

Once you have selected a configuration name and have chosen an identification string, click on the Pathmap tab. In the pathmap tab, you specify how Eclipse translates local path names to remote path names. To map a path, click on the New button to create a new map. If your web server is located on the same system that Eclipse is running on, both of these paths will be the same. In either case, under Local Path enter the path to the root of your project on the machine that Eclipse is running on. In Remote Path, enter the path to the root of your project on the machine the web server is running on.

debug configuration remote map path

Once you have specified the proper pathmap, press the Debug button to begin the debugger.

Now in your browser you will need to start the XDEBUG_SESSION, so type in the following


If you have set your ide string different you will need to change "firstProject" to reflect that. The default ide string is "testID".

The debugger should stop at the breakpoint that we set earlier.

Last modified 8 years ago Last modified on Mar 11, 2009 1:16:15 PM

Attachments (6)

Download all attachments as: .zip