Replacing the included PHP Xdebug module in MAMP Pro

Introduction

I'm a fan of MAMP Pro (https://www.mamp.info/mamp-pro/). I do all my web development work on a Mac and I like the simplicity of having one MySQL server, one Apache (or Nginx) server, a centralized GUI tool for modifying /etc/hosts, and I can switch between any of the supported PHP versions by linking a virtual host to a different PHP-FPM service.

Where MAMP Pro fails me is that I am reliant on the PHP versions they have made a decision to build into the the app. Each PHP-FPM service is actually installed with the app's package. MAMP doesn't use the OS' PHP, and I'm mostly okay with this.

Unfortunately, the most recent version of PHP 7.3 that has been included in MAMP Pro 5.7 is PHP 7.3.9. There are probably a lot of reasons why I should be using a more current version of PHP (7.3.19), but this old PHP version also means that MAMP has bundled a bugged version of Xdebug (2.9.0). This particular version of Xdebug has a bug that will cause the PHPStorm debugger to trigger at the declaration of a function that contains a breakpoint rather than at the actual breakpoint. More information on this Xdebug 2.9.0 bug is at https://bugs.xdebug.org/view.php?id=1727.

Luckily, Xdebug is a module and not part of the actual PHP build. Modules can be compiled independently of the PHP code and I was able to easily upgrade the Xdebug that is included as part of MAMP. The Xdebug module does need to have knowledge of the PHP that you are going to install it into, so for that reason you can't simply link the PHP-FPM service to another Xdebug installed somewhere else for another PHP.

Xdebug has a great tool to assist: http://xdebug.org/wizard.

I use a Homebrew installation of PHP CLI instead of MAMP and simply following the standard Xdebug install or compile instructions would lead the an Xdebug module that was configured the the CLI PHP and not MAMP's PHP.

So some slightly modified instructions for when you get to the phpize part of the compile instructions found on http://xdebug.org/docs/install. My paths are based on a standard MAMP Pro installation on a Mac and are specific to PHP version 7.3.9 that comes with MAMP Pro 5.7.

Instructions

1. In a new Terminal window, enter /Applications/MAMP/bin/php/php7.3.9/bin/php -i.
2. Copy-and-paste the output of this command into the textarea that appears on http://xdebug.org/wizard.Click the form button to analyze your MAMP's phpinfo() output.
3. Follow the presented instructions, including downloading the most recent version of Xdebug to your ~/Downloads folder (xdebug-2.9.6.tgz at the time of this post)
4. If you used Mac OS's tar extractor instead of the tar command, you may have to go one level deeper for step 4 of the Xdebug instructions (cd ~/Downloads/xdebug-2.9.6/xdebug-2.9.6).
5. For step 5 on that page, you are instructed to run phpize from within the source code directory. Substitute this command: /Applications/MAMP/bin/php/php7.3.9/bin/phpize.
6. For step 6 on the Xdebug instructions, substitute this command: ./configure --with-php-config=/Applications/MAMP/bin/php/php7.3.9/bin/php-config.
7. Run make as normal from within the source code directory.
8. Follow the cp instructions on step 8. It should be something like: cp modules/xdebug.so /Applications/MAMP/bin/php/php7.3.9/lib/php/extensions/no-debug-non-zts-20180731 (make sure you are still inside the Xdebug source code directory)
9. You will not have to edit the MAMP php.ini file as instructed in step 9 of the Xdebug compile installation instructions. This is because we are replacing the older version of Xdebug with our newly compiled one. The MAMP php.ini will include the Xdebug module (xdebug.so) when you enable Xdebug in the MAMP Pro GUI.

Hopefully this helps you. It still might be better to build a whole new PHP, with a more up-to-date Xdebug, to replace the outdated PHP 7.3.9 that is currently included with MAMP Pro 5.7. However, this was quicker and simpler for me to accomplish, probably because of the great instructions wizard included on xdebug.org, and this solution got me back in business with PHP 7.3.

Consider supporting continued Xdebug development financially: https://xdebug.org/support