Xdebug Installation – Issues and Solutions

I use PHP in my personal day to day projects. I use the Eclipse based PDT as my IDE of choice. Debugging is an important part of the programming activity, and I use Xdebug for all the PHP development I do.

Many times I had issues installing it, making various mistakes. The current article is a step by step check list to be used to troubleshoot the Xdebug installation.

1. Ensure you have the right library.

You need the windows / linux library and you need the right version, the non thread safe or the thread safe one, depending on the PHP build you are running. Many times this is difficult to spot, so the XDebug developer installed a tool at the url http://xdebug.org/wizard.php. Use it. Get the output produced by PHP after running the command php -i and paste it in the huge textarea provided. After a second, you will be prompted with the right version to download.

2. Ensure you install it properly

  • Download the DLL
  • Copy it in a folder, preferably together with the other PHP extensions. Personally I always install PHP in the c:\php folder and always copy all the extensions, including Xdebug in the same folder. Then install the folder in the system path.
  • Configure it properly in the php.ini. The thread safe version must be installed under zend_extension_ts property name, while the non thread safe version must be installed under zend_extension
  • Rather than relying on the system path, better provide a full path to the dll

3. Ensure it was picked up by php

Restart the apache server or restart the php server mode (php -S localhost:80) if you are running php 5.4 or higher, then install a page containing phpinfo(); command and see if xdebug is listed in the provided page. If it is not, you made a mistake, you should see it in the apache or php logs, probably an error loading the dll.

You should see something like the following:


And if you see that, scroll down and you see all the properties associated with xdebug:


4. Ensure the parameters are set correctly

  • The port is automatically set to 9000, ensure the IDE is set to the same. Ensure there is connectivity from the server to the client. Two times when performed installation (including the most recent one) I had port 9000 kept busy by another process and had to move the installation to other port, I eventually chose 9211.
  • xdebug.remote_mode property should be set on req. I believe it works with any other value, but I prefer this one
  • xdebug.remote_host should be set to the right value. Most of the time the xdebug on the server will connect to the IDE on the same machine, so the default value localhost should be fine. If this is not the case, double check the connectivity from the server to your IDE machine.
  • xdebug.remote_enable MUST be set on On.
  • After the changes are done, always restart the php (if you use the standalone php setup php -S) or restart Apache. Then bring up the page with phpinfo(); in it and ensure the values are captured as expected.

5. Ensure the IDE is properly configured.

If you use PDT, make sure that

  • Xdebug is configured as the default debugger for PHP
  • The port corresponds with the one that is set in php.ini
  • Most important - in order to debug, you need to create a debug configuration where the starting page is specified, the url and all the other parameters. Ensure that the selected debugger is xdebug. (It is very easy to do this mistake, you have a drop down there and the first value is default selected, and this will be never Xdebug as X is to the end of the alphabet) Does not matter what default debugger settings you have and what settings you got associated with the xdebug in your client, if you select other debugger in the debug configuration, it will just not work.


Let's review the most important checks again

  1. Double check xdebug is the right version, properly installed and properly loaded by php
  2. Double check the settings and ensure that port and machine name match IDE with the server installation
  3. Ensure xdebug.remote_enable is on
  4. Double check when you start the debugging on the PDT side that you actually selected Xdebug as the debugger

Here is how it is configured on my machine:

zend_extension = C:\php\php_xdebug-2.2.0-5.4-vc9.dll

That should be all. Good Luck!