Little Black Hat

A debugger is one of the most powerful development tools available. However, with PHP, debugging a site can be tricky. A lot of times, the host you need to debug is remote. Xdebug, the PHP debugger, solves this problem with their remote debugging feature.

Unfortunately, getting remote debugging with xdebug setup on Mac OS X can be a little tricky. This tutorial will help you setup your environment for easy remote debugging using Xdebug and MacGDBp.

Configuring Xdebug

First, you need to install and enable xdebug on your preferred remote machine. You can find directions for installing xdebug on Mac OS X with Macports here. Once you have xdebug installed, you will need to setup some configuration options.

You will need to add these lines, with modification, to your .htaccess configuration file.

php_value xdebug.remote_enable                  on
php_value xdebug.remote_host                    <ip or hostname of your machine>

The first configuration directive enables remote debugging. It is disabled by default for security reasons.

The second configuration option specifies the host that can access remote debugging. You don’t want to just open up xdebug to any host, this is a major security risk. You should set this directive to the IP address or hostname your server will see when you attempt to connect.

There are a lot more configuration options available. Take a look at them from the Xdebug documentation here: http://xdebug.org/docs/remote

Configuring MacGDBp

First, go get a copy of MacGDBp here: http://www.bluestatic.org/software/macgdbp/

MacGDBp requires you to map your local path to the remote path on the server. This allows MacGDBp to map your local filenames to the remote filenames that get sent by xdebug. You can map these paths in the Paths preference pane. This is how you set them up.

First, open up the preferences for MacGDBp. From the toolbar, choose the “Paths” button. This pane lets you configure your local and remote paths. Under the local setting, put in the path to your site code root. Under the remote setting, put the path to the site code root on the remote server.

MacGDBp Paths Preference Pane

In the example above, the code for example.com is located locally at:

/Users/khallmark/Sites/example.com

On my remote server, the code is located at:

/path_to_code/example.com

Setting breakpoints

By default, MacGDBp will stop at the first line of execution. This isn’t very useful for a large application with many files and code paths. You would be clicking through for a long time. You can solve this problem by setting some breakpoints.

MacGDBp Window Menu

To open the breakpoint editor, open the window menu and select the “Breakpoints” option.

Setting Breakpoints in MacGDBp

To create a breakpoint, click the plus in the lower left hand side of the screen. From the file browser, choose the file you want to debug. The file will appear in the top pane. Click on one of the line numbers to set a breakpoint. You will see it appear in the bottom pane of the screen. You can set as many breakpoints as you need to.

Debugging Normal Page Requests

Once everything is setup, actually debugging your code is easy.

Open up the page you want to debug, for this example:

http://www.example.com/index.php

To begin debugging, you will need to set the XDEBUG_SESSION_START variable in your get string. This can be any value, as long as you use it consistently. For our example, it would look like this:

http://www.example.com/index.php?XDEBUG_SESSION_START=some_name

Once you set this variable, xdebug will automatically attempt to connect to your remote client. When you are done, make sure you pass the variable XDEBUG_SESSION_STOP to end your debugging session.

http://www.example.com/index.php?XDEBUG_SESSION_STOP

Debugging AJAX Requests

Debugging AJAX requests is a bit trickier. You can’t always pass the debugger the XDEBUG_SESSION_START variable with these types of requests. To debug AJAX requests, you will need to add another configuration option to your .htaccess file.

php_value xdebug.remote_autostart            on

When this value is set, xdebug will try and connect to the debugger automatically. Make sure you turn this option off when you’re done.

Fin