Installing Xdebug

The most difficult part of setting up MacGDBp is setting up the Xdebug extension. You cannot use the built-in web server because that version of PHP will not properly execute Xdebug. Instead, the easiest method is to download MAMP. After installing Mamp, you have to install Xdebug.

  1. Download a compiled version of the Xdebug extension from Komodo. Select either “Mac OS X / PowerPC” or “Mac OS X / x86” under “PHP Remote Debugging.”
  2. Copy the xdebug.so file from the folder that matches your MAMP PHP version to /Applications/MAMP/bin/php5/lib/php/extensions/no-debug-non-zts-20050922/
  3. Open /Applications/MAMP/conf/php5/php.ini and add a semicolon (;) at the beginning of this line: zend_extension_manager.optimizer=/Applications/MAMP/bin/php5/zend/lib/Optimizer-3.2.2

Configuring Xdebug

If you have Xdebug installed or you just installed it using the above steps, it is time to edit your php.ini file to configure Xdebug.

  1. Open up /Applications/MAMP/conf/php5/php.ini for editing in a text editor.
  2. Add these lines at the top of the file (each one will be explained later): zend_extension="/Applications/MAMP/bin/php5/lib/php/extensions/no-debug-non-zts-20050922/xdebug.so"
    xdebug.remote_enable=1
    xdebug.remote_host=localhost
    xdebug.remote_port=9000
    xdebug.remote_autostart=1
  3. zend_extension: This is the path to the xdebug.so extension file. The path to this file is given as the last line of output from the installation process (see above).
  4. remote_enable: Enables the remote debugging functionality.
  5. remote_host: The address of your computer. If you are running a local web server, "localhost" means the same machine as the web server. However, if you are debugging from a hosting environment, this will be your IP address or hostname.
  6. remote_port: The port to connect to. Set this to be the same as the port number in the MacGDBp preferences. If you are using a remote_host other than "localhost," make sure your router will forward the port to your computer!
  7. remote_autostart: This tells the server to try and connect to a debugger on every page load. This is not recommended in production environments! With this setting enabled, every time that MacGDBp is open, the server will connect to it and debug any PHP page.

For a list of more settings and deeper explanations, see this website.

Remote Debugging

To debug on a PHP installation that is running on a machine other than your local computer (localhost), you will need to edit php.ini on the server. MacGDBp will merely listen for any connection coming into your computer on port 9000. The Xdebug extension works by connecting to the specified host and port in php.ini; if MacGDBp is running on the specified host, then the two will connect. In order for this to work, particularly if your server is not on your local network, you will need to have your home router forward all data coming in on port 9000 to your computer. Make sure that your Mac's firewall also allows this. See the above configuration section for more information.

Perpetually Disconnected Status or Socket Errors

The “could not bind to socket” error means that MacGDBp cannot bind to port 9000, which means something else is already using that port. If you got this upon the first launch of MacGDBp, check if another application is using this port. Also, check your firewall. If you had opened MacGDBp and then this error happened, try closing and reopening the application, and restart if all else fails.