Table of Contents

Installing Xdebug

The most difficult part of setting up MacGDBp is setting up the Xdebug extension. You cannot use the built-in macOS web server because that version of PHP will not properly execute Xdebug. Instead, the easiest method is to use something like Homebrew to install PHP, Apache, and Xdebug using the php-xdebug package.

Configuring Xdebug

Once Xdebug is installed, you may need to configure it. Open the php.ini file in a text editor and ensure that the following lines are present:

xdebug.remote_enable=1
xdebug.remote_host=localhost
xdebug.remote_port=9000
xdebug.remote_autostart=1

• remote_enable: Enables the remote debugging functionality.
• 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.
• 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!
• 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 the Xdebug website.

Syntax Highlighting

MacGDBp can highlight the PHP code displayed in the source viewer. To do this, it needs access to a PHP binary executable. Prior to macOS 12 Monterey, Apple shipped one by default at /usr/bin/php. On macOS 12 and newer, you will need to specify your own PHP. This can be done in MacGDBp –> Preferences –> PHP Executable Path. This setting is new as of MacGDBp 2.1.

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.

Using Remote Paths

If you do not debug PHP scripts locally, but on a remote server, the file paths of your scripts will likely be different. This means that setting breakpoints will not work as expeted; MacGDBp will tell Xdebug (running on the remote server) to set a breakpoint for a file that’s on your local machine. The only time this happens is when breakpoints are set; all other operations that involve source code are done via Xdebug (including viewing source). To use breakpoints with a remote instance, you will need to keep two copies of the source code: one on the remote server and one locally (or you can mount the remote server). Then open MacGDBp –> Preferences –> Paths. The path replacement system works by transforming a path on your local computer into the one on the remote server. When you add a breakpoint path, it will replace all the “local paths” from the replacements pane to create the remote path of the source code.

For example, if I were debugging a remote website where the local source was on my computer, this is how I’d set it up:

• Local Path (OS X): /Users/robert/htdocs/mywebsite
• Remote Path (Linux web host): /home/hosting_company/public_html

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.

If you use PHP with FastCGI, many default configurations use port 9000 to communicate with the web server (e.g., Apache). This will conflict with the default Xdebug port, so you should resolve the conflict by changing one of the ports. The port that MacGDBp tries to connect to is set in Preferences.