Setting up Xdebug on Mac OS X (or Win32 / Linux)
Posted by Felix Geisendörfer, on Sep 21, 2007 - in Coding Techniques & Tools » Tools
If you want to take your debugging to the next level by getting a nice stack / function trace on errors that occur, then you should check out Xdebug by Derick Rethans (who I had the pleasure to meet at php|works). I've only been touching the surface of this powerful extensions so far, but its already been a pleasure to work with and I'll try to write more about it in future. Maybe I can even integrate it into the CakePHP test suite for code coverage analysis at some point.
Anyway, one of the biggest obstacles when getting started with Xdebug was that I had a hard time finding good instructions on how to set it up on Mac OS X (I finally got rid of windows, yeah !). The only good resource I found was stored in Googles cache (wasn't live anymore) and had instructions on how to manually build xdebug from source. However, I didn't have a lot of time back then and compiling would have involved setting up all kinds of additional tools. This was the point when I vaguely remembered that the Komodo IDE was using xdebug. So I did some more research and sure enough, the good folks over at ActivateState actually provide their Xdebug binaries as stand-alone downloads for all major platforms.
On my macbook I'm using MAMP, but the basic concept of setting this up should be cross plattform:
- Download the latest Xdebug binaries for your OS from: http://aspn.activestate.com/ASPN/Downloads/Komodo/RemoteDebugging
- Copy the xdebug.so / xdebug.dll for your PHP version to your extensions directory (for MAMP this was: /Applications/MAMP/bin/php5/lib/php/extensions/no-debug-non-zts-20050922/xdebug.so, in Windows its probably C:\php\modules\xdebug.dll)
- Find your php.ini file (for my MAMP install this was in /Applications/MAMP/conf/php5/php.ini, under Windows it should be C:\Windows\php.ini)
- Add the following lines to your php.ini configuration (MAMP):
-
[xdebug]
-
zend_extension=/Applications/MAMP/bin/php5/lib/php/extensions/no-debug-non-zts-20050922/xdebug.so
or for Windows:
-
zend_extension_ts="c:/php/modules/xdebug.dll"
To test if things worked or not run a phpinfo() script and see if xdebug shows up in your list of extensions (you'll probably have to restart Apache first). Once that is accomplished you can start to indulge yourself in discovering all the various configuration options and functions there are.
One of my favorite settings allows to make all file paths that show up in error messages turn into links that will open my text editor for the given file at the right line. For Textmate this is simply a matter of adding this line to your php.ini:
-
xdebug.file_link_format = "txmt://open?url=file://%f&line=%l"
Check the manual of your editor of choice to see what "protocol" it is using for accomplishing the same thing. Also make sure to check out if your editor happens to have built-in Remote Debugging support for Xdebug. A list of those editors can be found in the Xdebug documention (Textmate is not in there yet : /).
Alright, I hope some of you find this useful. If you run Windows or Linux there are also more detailed instructions on the Xdebug website itself, I just found the lack of OS X info out there worth making this little blog post. Kudos go out to Derick for writing this awesome extension and ActiveState for providing Mac OS X (and other plattform) binaries for all kinds of PHP versions.
-- Felix Geisendörfer aka the_undefined
33 Comments
For Linux users - http://protoeditor.sourceforge.net/ has a nice lightweight client for Xdebug which is also available as a plugin for Kate (this is not mentioned on the Xdebug site)
Xdebug also runs happily with XAMPP - if you figure out where to put the compiled .so file ;)
Tarique: Thanks for that info.
@Everybody: There also is an article describing on how to install Xdebug on Linux w/ XAMPP on the SaniSoft blog: http://www.sanisoft.com/blog/2007/06/23/how-to-install-xdebug-php-extension-for-xampp-on-linux/
The link to my wrapper is http://cakeexplorersamples.googlecode.com/files/nppwrapper.rar
Also i integrate this solution with cakephp (Footnotes article on bakery)
Soon I create extended article (where will possible to open files from cake stack trace)
Felix Geisendorfer's Blog: Setting up Xdebug on Mac OS X (or Win32 / Linux)...
...
Together with xdebug phpcoverage detects your test coverage while running your testsuite. This is really helpful to find important parts in your application which are still untested:
http://developer.spikesource.com/wiki/index.php/Projects:phpcoverage
[...] Felix Geisendorfer shows, in a new blog post today, how to setup XDebug (the popular debugging extension for PHP) on a Mac OSx (or Win32/Linux) system. One of the biggest obstacles when getting started with Xdebug was that I had a hard time finding good instructions on how to set it up on Mac OS X (I finally got rid of windows, yeah !). The only good resource I found was stored in Googles cache (wasn’t live anymore) and had instructions on how to manually build xdebug from source. [...]
I just installed it through pecl and added the zend_extension line to php.ini
Works prefectly.
For those with fresh installs of MAMP make sure that you add the xdebug directives to the bottom of the php.ini file (after the ZendExtension manager). Also switch to php 4 and turn off APC in the MAMP control panel.
Awesome! Thank you!
Thanks for sharing this, Felix! Works perfectly :)
It installed no problem through macports in OS X 10.5 for me. Thank you for the pointer!
Thanks for sharing this!
Just got xdebug 2.1dev running today with leopard. The file_link_format is proving to be very useful when developing locally. Thanks.
These instructions worked *nearly* perfectly for me. One little hitch (on my 2.4 Ghz Intel Core Duo iMac) is that I had to disable the "Zend Optimizer".
On Leopard, both the pecl install and the Komodo download worked... but they needed to be referenced in php.ini with this line:
extension=/usr/lib/php/extensions/no-debug-non-zts-20060613/xdebug.so
The "zend-extension=" line would not load the extension for me.
You wrote:
>On of my favorite settings allows to make all file paths ...
Should be:
>One of my favorite settings allows to make all file paths ...
Thx Antonio - fixed.
@scum - that's because it's zend_extension not zend-extension.
For everyone else: This one of the best XDEBUG tutorials I've seen yet:
http://devzone.zend.com/article/2803-Introducing-xdebug
It will totally get you started on how to properly configure its options, and what to do with its output.
Happy bug hunting!
-xentek
I ran into some problems when I added the xdebug.so line in my php.ini. For some reason the Zend optimizer had a conflict with xdebug. The php_error.log showed the following error:
[30-Mar-2008 17:17:32] PHP Fatal error: [Zend Optimizer] Zend Optimizer 3.2.2 is incompatible with Xdebug 2.1.0-dev in Unknown on line 0
Apache wouldn't start anymore!
I solved by turning off the Zend Optimizer in php.in:
;[Zend]
;zend_optimizer.optimization_level=15
;zend_extension_manager.optimizer=/Applications/MAMP/bin/php5/zend/lib/Optimizer-3.2.2
;zend_optimizer.version=3.2.2
;zend_extension=/Applications/MAMP/bin/php5/zend/lib/ZendExtensionManager.so
Cheers, Olivier
Be careful of getting the latest xdebug.so. The version I found was v2.1.0-dev, which has some problems with the most recent version of Eclipse and PDT. Tripped me up for quite some time.
From the Eclipse newsgroup:
---
A change has been made in the xdebug 2.0.3 which appears to causes a problem for PDT using xdebug. So at this time it is not recommended to upgrade to 2.0.3 and to continue using xdebug 2.0.2 with PDT 1.0.2 and the PDT 1.1 Nightly/Integration builds.
---
The only way I found to get the old version is to download the source from xdebug.org and compile it. If you don't have the Xcode tools, they are not hard to install: insert Disc 2 from the install CDs, open the "Xcode Tools", double click on the XcodeTools.mpkg, and go outside for a bit and enjoy the weather. When you come back, greb the 2.0.2 version of xdebug, unpack it, go to that directory in a terminal, and follow the directions in the README.
After compiling xdebug and failing to get the server to start back up, this was nice to find.
@Olivier
Yes, the install docs on the xdebug site state:
Xdebug does not work together with the Zend Optimizer or any other Zend extension (DBG, APD etc). This is due to compatibility problems with those modules. We will be working on figuring out what the problems are, and of course try to fix those.
I only had to comment out this line
zend_extension=/Applications/MAMP/bin/php5/zend/lib/ZendExtensionManager.so
to get it all working.
Great tutorial! Thanks!
On Mac OS X (Leopard) on Intel Core 2 Cuo processors, the pre-built binaries do not seem to work. Instead, grab the xdebug binaries at http://xdebug.org/ and in the downloaded directory run:
phpize
then
MACOSX_DEPLOYMENT_TARGET=10.5 CFLAGS="-arch ppc -arch ppc64 -arch i386 -arch x86_64 -g -Os -pipe -no-cpp-precomp" CCFLAGS="-arch ppc -arch ppc64 -arch i386 -arch x86_64 -g -Os -pipe" CXXFLAGS="-arch ppc -arch ppc64 -arch i386 -arch x86_64 -g -Os -pipe" LDFLAGS="-arch ppc -arch ppc64 -arch i386 -arch x86_64 -bind_at_load" ./configure --enable-xdebug
This will create the module you want in the `modules` directory. Copy these into your php extensions directory (probably /usr/lib/php/extensions/no-debug-non-zts-20060613).
Add
extension=xdebug.so
to your php.ini
Restart apache. And you should be good to go.
scum: I run the same setup as you (unless you really mean cuo processors, not duo ^^) and the binaries from komodo work for me.
For what it's worth... I could not get the komodo binary to work for me and I am on the same setup as Felix (same Macbook, MAMP, etc.).
In my apache error logs I could see that the extension failed to load but no clues as to why. I finally compiled everything myself from the binaries on the xdebug site (using version 2.0.2, not the latest also using my own install of phpize... not MAMP's. It is a very fast configure and make so don't worry), copied that over into the extensions dir and Felix's direction then worked fine.
Stuart: Tried disabling zend optimizer?
This was great, thanks. I've got everything going...sorta.
I have two issues: a.) the debugger will not stop at a checkpoint on my *second* page. Checkpoints on the first page are fine. b.) the implicit_flush doesn't seem to work. On or off, I only see my page after the php page completes. I'm running:
Leopard 10.5.3 on 2.4GHz Intel Core 2 Duo.
MAMP 1.7.1, Zend Engine v2.2.0, Xdebug v2.1.0-dev.
Recommendations where to start digging into this?
compiled xdebug 2.0.2 as instructed above. both issues resolved. :-)
To all with issues enabling the extension with MAMP PRO, it seems to ignore the ini @ '/Applications/MAMP/conf/php5/php.ini' completely.
On server start-up it actually overwrites '/Library/Application Support/living-e/MAMP PRO/conf/php.ini' (which is the config loaded by php, see phpinfo();) with the one stored inside the .app contents.
So you need to edit you need to edit '/Applications/MAMP PRO x.x.x/MAMP PRO.app/Contents/Resources/php5.ini'
Hope this helps some people.
Luke: Top job on picking that up. I've been banging my head against the wall trying to get this up and running on MAMP Pro. All sorted now though - and using the Komodo binaries. Cheers.
Leopard 10.5.4 on 2GHz Intel Core 2 Duo.
MAMP Pro 1.7.1, Xdebug v2.1.0-dev.
Felix: Yes, I had done that. I'm as certain as I can be that I tried everything (but you know that feeling of "I'm certain I haven't missed anything and it STILL isn't working" and then you find you have indeed missed something). Compiling things myself ended up working for me so for others who are comfortable with terminal and configure, make, make install may just want to go that route.
@Luke: I just spent the better part of an hour trying to figure out why MAMP Pro 1.7.1 refused to load the php.ini configuration files. In the end, I simply used the MAMP Pro menu to get File->Edit Template->php5 php.ini and include the directives there. Thanks for pointing out where this template file actually resides.
> xdebug.file_link_format = "txmt://open?url=file://%f&line=%l"
For widows system there is two way for using textmate style links.
First - use E-texteditor that very young. I dislike it even most of bundles implemented but functionality is very very young.
The second is my solution. I create universal wrapper that process such links and start extarnal application (editor). In mmy case i use notepad++ that also use xdebug for debuging php code.
Also in future i plan to integrate textmate bundles and scripts in it.