Requirements

Xdebug

You need to have the Xdebug extension installed. On Ubuntu Linux, type the following in a shell:

sudo apt-get install php5-xdebug

For other operating systems, refer to the Xdebug documentation.

Once the extension is installed, make sure that it's listed in your php.ini file. Depending on your platform, the installer may have done this for you. Note that the Ubuntu package maintains several php.ini files for you. It's automatically added to the apache2-version, but you have to explicitly add it to /etc/php5/cli/php.ini, if you want to debug shell scripts.

Your php.ini file should contain a line like the following:

zend_extension=/usr/lib/php5/20060613/xdebug.so

(The path may differ)

Further down php.ini, there should be a section for xdebug. If it's not there, just add it. For starters, add the following entries (Most of them are just default values, so they aren't strictly needed):

[xdebug]
xdebug.remote_autostart = 1
xdebug.remote_enable = 1
xdebug.remote_host = localhost
xdebug.remote_port = 9000
xdebug.idekey = SPECTATOR

Note: If you use Windows, you must list 127.0.0.1 instead of localhost.

Restart your webserver (Apache) after making changes to php.ini. On Linux, type the following in a shell:

sudo apachectl restart

or if you use a newer version of Apache:

sudo apache2ctl restart

On Windows, use the tray icon to restart Apache.

XulRunner

To run Spectator, you need to have XulRunner installed.

On Ubuntu Linux, just type this in a shell:

sudo apt-get install xulrunner

For Windows, you can simply grab the bundled download, which includes XulRunner for Windows.

If you use another OS, refer to Mozillas documentation.

Network

Spectator has a TCP-server built in, which listens for incoming debug-session. If your OS has a firewall, you will need to allow this traffic. Likewise, if you want to do remote debugging, it must be possible for the host to connect to you. However, in these cases, it's probably better to use ssh-port-tunnelling instead.

SSH Tunneling

If your application runs on a remote machine, you can debug it by ssh'ing in to the machine, and tunnel connection through. Basically, connect to the remote machine, using the following format:

ssh -R 9000:localhost:9000 you@example.com

Todo: I'm not sure how to do this on Windows. Anyone with experience on this, please add to the wiki.

Using the debugger

See StartingDebugSession