After figuring out a way around the massive breaking change introduced by Xcode 11, it's now time to install Xdebug back on MacOS Catalina.

Long story short, Apple decided to nuke /usr/include in MacOS Catalina, which has been the default location for C header file for ever in UNIX systems. Trying to install through PEAR / PECL will return an error as the compiler will look for necessary headers file in /usr/include. So the solution is to compile Xdebug manually, manually specifying the actual location of the header files, which are still provided by Xcode, just at a different location.

Xcode

The first step is to get Xcode from the App Store.

Once Xcode installed, we have to get the command line tools :

xcode-select --install

You might need to actually open Xcode at this point to finish installation and accept terms and conditions, especially if the previous command fails.

Finally, make sure the SDK is found. If the path you get differs from the one bellow, you might need to edit the path accordingly later on:

$ xcrun --show-sdk-path

/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk

Manually Compiling Xdebug

Getting source

Let's compile 2.7.2, getting the source code from git. Alternatively, you can download the source from Xdebug site.

git clone https://github.com/xdebug/xdebug.git
cd xdebug
git checkout tags/2.7.2

phpize

Next we need to make a copy phpize so we can edit the include path :

cp /usr/bin/phpize .
nano ./phpize

Find this line :

includedir="`eval echo ${prefix}/include`/php"

...and replace it with this line :

includedir="/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/php"

Run phpize:

./phpize

You should now see something like this :

Configuring for:
PHP Api Version:         20180731
Zend Module Api No:      20180731
Zend Extension Api No:   320180731

Configure & build

We can now configure :

./configure --enable-xdebug

...and run make using our custom SDK location defined as compiler flags. I used a variable to store the path to the SDK so it's easier to edit if it changes :

SDK_PATH=$(xcrun --show-sdk-path)

make CPPFLAGS="-I${SDK_PATH}/usr/include/php -I${SDK_PATH}/usr/include/php/main -I${SDK_PATH}/usr/include/php/TSRM -I${SDK_PATH}/usr/include/php/Zend -I${SDK_PATH}/usr/include/php/ext -I${SDK_PATH}/usr/include/php/ext/date/lib"

You might see some warning, just ignore it for now. Finally, we'll need to run :

make install

Again, this command will fail because it can't move the extension to the right place. SIP will prevent it. But no worries, we'll take care of that manually at the next step. make install is still required as it will sign the *.so file.

The above trick should work for any PHP extension you want to compile. If you're trying to compile something other than a PHP extension, I recommend having a look at the Makefile to see which directory to include in your custom CPPFLAGS.

Enabled support in PHP

Once make install has been run, we can move the executable somewhere safe. I use /usr/local/php/extensions.

sudo mkdir -p /usr/local/php/extensions
sudo cp $(php-config --extension-dir)/xdebug.so /usr/local/php/extensions

Then we edit the PHP configuration to enable Xdebug. Simply edit php.ini:

sudo nano /etc/php.ini

And we add the following at the bottom :

[xdebug]
zend_extension=/usr/local/php/extensions/xdebug.so
xdebug.remote_enable=on
xdebug.remote_log="/var/log/xdebug.log"
xdebug.remote_host=localhost
xdebug.remote_handler=dbgp
xdebug.remote_port=9000

Restart built in server to be sure :

sudo apachectl restart

And finally test everything went fine :

php -i | grep "xdebug support"

If the above command returns nothing, then Xdebug is not available on your install. Go back the steps to find out what's missing.

References and thanks :

Previous Post Next Post