Cote de Azur

When I debug code, I find that a debugger is a very powerful tool. With a debugger you can set breakpoints, step through code, watch variables, do a stack trace, and much, much more. The eclipse PDT + XDebug offers a PHP debugger that you can use for free. It also offers a full PDT IDE (for editing, “building”, and debugging your PHP projects), but I use eclipse+PDT+XDebug only as a debugger since I like to use my favorite editor for editing. This guide shows how to setup eclipse+PDT+XDebug as your PHP Debugger.

This guide was written and tested using the R20080603 – 1.0.3 PDT all in one package. I also used XDebug 2.0.3. With versions other than PDT R20080603 and XDebug 2.0.3, there may be subtle differences from what I wrote here, or things may not work.

1. Make sure you have the latest version of Java installed.
2. Make sure you have Apache+PHP installed (such as using the XAMPP package)
3. Download XDebug
   1. Go to the XDebug page
   2. On right side of page, click on one of the Windows modules that matches your PHP version
   3. Download the .dll file and remember its file name the directory that you saved it in (I save it in “c:xamppphpext”).
4. Install XDebug
   1. Open your php.ini file in a text editor
      • In XAMPP, the default location for the php.ini file is “c:xamppapachebinphp.ini”
      • If not using XAMPP, you can find the location of php.ini by browsing to a .php file on your server that calls the phpinfo() function.
   2. Either uncomment (recent versions of XAMPP have this in php.ini, but commented) or add:
      • Note: substitute the right path/filename for your xdebug dll file

      [XDebug]
      ;; Only Zend OR (!) XDebug
      ; zend_extension_ts="C:xamppphpextphp_xdebug.dll"
      ; Modify the filename below to reflect the .dll version of your xdebug
      zend_extension_ts="C:xamppphpextphp_xdebug-2.0.3-5.2.5.dll"
      xdebug.remote_enable=true
      xdebug.remote_host=127.0.0.1  ; if debugging on remote server,
                                    ; put client IP here
      xdebug.remote_port=9000
      xdebug.remote_handler=dbgp
      xdebug.profiler_enable=0
      xdebug.profiler_output_dir="C:xampptmp"
      

      Note that “xdebug.profiler_enable” is set to 0 above instead of 1. This is not the default in the XAMPP php.ini, and I recommend changing it to 0. It was suggested to me to set this to 0 in order to not generate very large files.

   3. Comment out any Zend Optimizer in php.ini because it is not compatible with XDebug. For example, all of this should be commented out (using “;”):
      

      [Zend]
      ; zend_extension_ts = "C:xamppphpzendOptimizerlibZendExtensionManager.dll"
      ; zend_extension_manager.optimizer_ts = "C:xamppphpzendOptimizerlibOptimizer"
      ; zend_optimizer.enable_loader = 0
      ; zend_optimizer.optimization_level=15
      ;zend_optimizer.license_path =
      

   4. Restart your webserver for the php.ini to take effect.
   5. Test that the Xdebug install was successful
      1. Create a .php file that calls “phpinfo()”
      2. Open the .php file with “phpinfo()” in your browser
      3. Check for XDebug in the phpinfo page.
5. Download Eclipse PDT
   1. Go to the Eclipse PDT Download page
   2. On the download page, click the link for the latest release build in the “Build Name” column.
   3. On the release build page, select the windows ZIP file in the “PDT All in One Package” area
   4. On the mirror selection page, choose a mirror to download from and download the .zip file.
6. Install Eclipse PDT all-in-one
   1. There is no install .exe file to run.
   2. Unzip the all-in-one zip file to a temporary directory.
   3. Move the “eclipse” directory (created during unzip) to c:eclipse (I tried using “c:Program Fileseclipse” instead of c:eclipse, but it didn’t seem to work for me, so use c:eclipse).
7. Execute Eclipse for the first time + Setup XDebug
   1. Execute the c:eclipseeclipse.exe file.
   2. “Workspace Launcher” dialog box will appear, I just keep the default and press “OK”
   3. “Welcome” screen, click on “Workbench” icon on right side towards the middle.
   4. Eclipse Workbench, do: “Window->Open Perspective->PHP”
   5. File->New->PHP Project
      1. Project Name: assign a name such as “Server-docroot”
      2. Project Contents: uncheck “Default”, and browse to the document root of your web server. (remote server example)
      3. Click “Finish”
      4. You’ll now see a screen that gives you 2 options, choose the 1st option “Create project in directoryName (Deleting the project will delete the entire directoryName folder)”, and click “OK”.
         • Don’t ever delete this project from eclipse or it will delete your entire docroot.
   6. Change to PHP Debug Perspective: Window->Open Perspective->PHP Debug
   7. Window->Web Browser
      1. If “0 Internal Web Browser” is available, you can choose that to have the browser inside eclipse. I have found that this option is only present if IE is running before eclipse is launched, otherwise this option is not available.
      2. If “0 Internal Web Browser” is not available, I found that “0 Default system Web Browser” doesn’t seem to work for me and that I have to choose either Firefox or IE in order for debugging to work. If you really want to use the internal web browser, then quit out of eclipse, launch IE, and then launch eclipse again. The internal web browser option should be available now.
   8. If your webserver is on a remote machine, do the following now:
      1. Do Window->Preferences
      2. PHP->PHP Servers Window: Click “New”
      3. Name: Provide a name to refer to this server in eclipse
      4. URL: Enter the URL of the document root of the remote server
      5. Click “Next>”
      6. Server Path Mapping Window: Click “Add:”
      7. Path on Server: if the docroot on the server is at c:xampphtdocs on the server machine, then put that here, otherwise put the docroot path of the server (remember, c: is the server’s c: drive)
      8. Click on the radio for “Path in Workspace” and press the “Browse” button. Select the workspace resource corresponding to the docroot (should be the only thing listed – this should be the name of the PHP project that you provided earlier – this guide used the project name “Server-docroot” ), and click “OK”
      9. Click “OK” (in “Add New Path Mapping” window)
      10. Click “Finish” (in “PHP Server Creation” window)
          1. At this point, you might see a window titled“User Operation is Waiting”, just be patient until this window disappears on its own before going to the next step.
      11. Click “OK” in the Preferences-PHP Servers window.
   9. Run->Open Debug Dialog
      1. Double-click “PHP Web Page”
      2. “New configuration” is created as a sub-item under “PHP Web Page”, highlight it
      3. “Server Debugger”: should be “XDebug”
      4. “PHP Server”: choose “Default Web Server” (if your web server is on the same machine) or the remote server that you created earlier.
      5. “File”: Browse to a file in the project that should be launched in the browser for the debug session.
      6. If “Auto Generate” is checked (localhost example, remote server example, a URL to the chosen file on the server should be auto-generated and should look correct. If not (or if you want to add GET parameters), then it needs to be manually edited (after de-selecting “auto-generate”) to match the correct URL.
         • With the R20080603 PDT all-in-one package, it seems to add the project name into the URL when auto-generate is checked, which is not correct. You’ll need to uncheck auto-generate and remove the project name from the URL to make it work. It is unfortunate that it does this, the R20080103 (v1.0.2) release did not do that.
      7. Click “Apply”
      8. Click “Close”
8. Run debug session
   1. Do either: Run->Debug or F11 or click the bug icon in toolbar
      1. If a window pops up at this point which states “The selection cannot be launched, and there are no recent launches”, then do the following
         1. Run->Open Debug Dialog
         2. Highlight “New configuration” under “PHP Web Page”,
         3. Click the “Debug” button
      2. If the debug session isn’t starting, and you are seeing in the lower right corner “Launching New_Configuration” with a progress bar that keeps moving, then, then do the following:
         1. Click the button to the right of the progress bar.
         2. Now in the right pane you’ll see a red square button, click it to get out of this faulty debug session.
         3. If the web browser came up with the page you are trying to debug, it means XDebug is not installed on the server properly. Go back and get XDebug installed on the server and try again. One common mistake that causes this to occur is that you may have modified the wrong php.ini file, make sure you modified the right php.ini file. You can test if XDebug is installed properly by opening a .php file in your browser that calls phpinfo() and see if XDebug is in the resulting page – make sure this is the case. Also, make sure that xdebug.remote_host is pointing to the machine running your debugger (if you use a different machine to debug sometimes, you need to change this).
         4. If the web browser did not come up, then in the pull-down menus, do “Window->Web Browser”
         5. If it is set to “Default system Web Browser”, then this is the problem and you must switch off of it.
            1. If “0 Internal Web Browser” is available, choose it.
            2. If “0 Internal Web Browser” is not available, and you want to use the internal browser in eclipse instead of IE or Firefox, then quit eclipse, launch IE (and don’t close it), and launch eclipse again. Before running your debug session, do “Window->Web Browser” and check that “0 Internal Web Browser” is available. I have noticed that for some strange reason, if you don’t do “Window->Web Browser” before your first debug session, the internal web browser doesn’t seem to be available.
            3. If you want to use Firefox or IE, or if “0 Internal Web Browser” is available, then choose Firefox or IE
      3. If the “Confirm Perspective Switch” window pops up, check “Remember my decision” and click “Yes”
   2. You now have a debug session going, have fun setting breakpoints, stepping through code, and looking at variables!
9. Ending the debug session
   1. I have noticed that once the php script runs to completion, the debug session is still running. This is because if you navigate to another page it will also go through the debugger (this assumes that you have “Debug all pages” checked in Run->Open Debug Dialog;PHP Web Page/New Configuration;Advanced Tab).
   2. To end the debug session, allow the current PHP script to run to completion and then highlight the “Remote Launch” in the “Debug” window and press the red square button just above it to terminate the session.
10. Changing which file you want to debug
    1. If you want to debug a different PHP file, you will need to go back to the Run->Open Debug Dialog screen, and in PHP Web Page/New_Configuration, you’ll need to change both the file and the URL to the new PHP file.
11. Happy Debugging!

I haven’t used this debugger much yet as I have only gotten to set it up. I’ll be adding more notes when I learn more.

One of the limitations I’ve found is that for the first page you navigate to, it seems that you can’t specify what is to be given in the “POST” data of the webpage. If you want to debug the “POST” method to a PHP page, then make sure you have “Debug all pages” checked in Run->Open Debug Dialog;PHP Web Page/New Configuration;Advanced Tab. Then you should let the PHP script run to display a web page with a form. When you put the data into the form and submit it, the debugger will now allow you to debug this page with the POST data.

Useful Links:

Eclipse PDT Homepage
PDT Documentation Page
XDebug Guide