July 27, 2012

Code Debugging with Xdebug and Eclipse Juno [GUIDE]


This is the first of my series of  guides and walk-through on all code everything. I will try to take you through the complete steps to setup and configure Xdebug (v2.2.0) on a Win7 x86 PC using Eclipse Juno (4.2.0). For other versions and/or platforms, sorry but YOYO (you're on your own)! Just kidding, head over to Stack Overflow, they have some great guides there. Trust me I have been there


Setting up Eclipse is straightforward, so I'll assume you have PDT (PHP Development Tools) SDK, a web server (Apache 2.2.21), and a PHP engine (PHP 5.3.8). For a complete guide on how to set these up, click here. Let me start off by explaining a little bit about what Xdebug is... and what it isn't.

Xdebug is a compiled library (.DLL for Win7) written by Derick Rethans and can be found on the developer's site xdebug.org. This piece of code helps tremendously in the following areas of agile programming:


  1. Code Debugging: Whether done automatically using the remote debugger based on the DBGp protocol or manually with the use of API calls to the Xdebug library, debugging your PHP scripts can be done effortlessly using your favorite IDE. Traditionally, code debugging was done by using the var_dump() or print_r() functions. The thing is, whereas these two functions kinda worked the trick well, returning information about variables state is just a part of the debugging process. There is more info to be gathered other than the value of a certain variable at a certain point in your code.
  2. Profiling: This is the analysis of your code in search for slugs and bottlenecks. There are a couple of profiler visualizing tools like WinCacheGrind or Webgrind, a full-HTML implementation of the former.
If you installed your PHP web development stack well, you should be able to run the phpinfo() function and return a bunch of configuration values for your stack. Out of all this data (that you should keep secret when on production server by the way) we're only interested in the "Loaded INI configuration file". That's the file Apache uses to read and understand how to communicate with your PHP interpreter. It tells a couple of things:
  • Which compiler was used to build your interpreter. This is important when you're choosing a .DLL from xdebug.org. Make sure the compilers match correctly, especially if it is TS (Thread-Safe) or Non Thread-Safe (check for "TS" in the PHP extension build value in the  phpinfo()  feedback).
  • If there is another debugger in use. It is usually listed right below the scripting engine in use. The most common being the Zend engine, using the Zend debugger.
Now open the INI file in a text editor, in the [Zend] section comment out anything that begins with "zend_" by preceding it with a ";" and write the following under the [XDebug] section (or uncomment it in some cases, you should try and find each line first):

[XDebug]
zend_extension_ts="<path to php_xdebug.dll>"
xdebug.remote_enable=true
xdebug.remote_port="<the port for XDebug to listen to>" (the default port is 9000)
xdebug.profiler_enable=1
xdebug.profiler_output_dir="<PHP stack home\tmp>"

Now head over to Eclipse Juno and open the PDT preferences tab (expand the PHP tab under Window>Preferences). Under the Debug menu is where you specify details on the debugger to use.
That's it!
If you want to figure out if everything worked well, here is a nice piece of code that you'll run through the CLI (command-line interpreter, basically outside of Apache or a browser; just pure PHP) after you have typed the following in your browser: "http://localhost/dbgtest.php?XDEBUG_SESSION_START=ceable"
<?php
$address = "localhost";
$xdebug_port = 9000;
$sock = socket_create(AF_INET, SOCK_STREAM, 0);
socket_bind($sock, $address, $xdebug_port) or die('Unable to bind');
socket_listen($sock);
$debug_client = socket_accept($sock);
echo "connection established: $debug_client";
socket_close($debug_client);
socket_close($sock);
?>

The command-line window should print something like "connection established: Resource id #5". If it didn't happen, you missed out on something important and should read this page again to figure out where you went wrong, but that's another topic...

[UPDATE]: I forgot to include the xdebug test script :). Remember, you MUST run this script through the CLI and then open a browser to the address specified above (change to your specific domain if doing remote debug) and watch the output on the CLI terminal.

5 comments:

  1. so, this is as far as I got.
    Whens the rest comming? :>

    ReplyDelete
  2. Great you managed! Sorry been up in other projects and completely forgot about my blog. New content coming soon... Happy new year!

    ReplyDelete
  3. Replies
    1. I read/heard good stuff about the Codelobster debugger... how is going for you? I tried a couple of others but none really match Xdebug. But maybe you have something to change my mind.

      Delete
  4. I've followed these instructions but I still had issues. Port 9000 can't be bound to because Eclipse seems to be using it. However, I noticed that the only way I could get xdebug to work with Apache is when the site is running on port 80. As soon as I change my site to run on a different port, xdebug hangs. I wonder if there's a setting that ties the two together. I have more than one site running in Apache and would like to debug each of them without having to reconfigure the ports. Anyone had this issue before? or knows how to fix it?

    ReplyDelete

Share in your comments!...