Installation of Xdebug on MacOS for PHPStorm

Question

I’m facing a lot of issues installing Xdebug on my macOS.

From the phpinfo page, I see that the php.ini file I’m using is in/etc/php.ini. While following some tutorials such as this, it was mentioned that the [xdebug] section should just be commented out. I happen to not see it at all at the bottom of the page, and just included it as per the tutorials, and ever since that change my php -v will produce this output

Failed loading /Applications/MAMP/bin/php/php7.3.9/lib/php/extensions/no-debug-non-zts-20180731/xdebug.so:  dlopen(/Applications/MAMP/bin/php/php7.3.9/lib/php/extensions/no-debug-non-zts-20180731/xdebug.so, 0x0009): code signature in (/Applications/MAMP/bin/php/php7.3.9/lib/php/extensions/no-debug-non-zts-20180731/xdebug.so) not valid for use in process: mapping process is a platform binary, but mapped file is not
PHP 7.3.9 (cli) (built: Nov  9 2019 08:08:13) ( NTS )
Copyright (c) 1997-2018 The PHP Group
Zend Engine v3.3.9, Copyright (c) 1998-2018 Zend Technologies

I was primarily using php 7.3.9 before trying xdebug, and I also tried some solutions such as this, this and this, which mainly gave me a failed ‘make’ and blank PHP API versions. This is a trace of running sudo pecl install xdebug from the first solution

Password:
downloading xdebug-2.9.4.tgz ...
Starting to download xdebug-2.9.4.tgz (243,689 bytes)
..................................................done: 243,689 bytes
91 source files, building
running: phpize
grep: /usr/include/php/main/php.h: No such file or directory
grep: /usr/include/php/Zend/zend_modules.h: No such file or directory
grep: /usr/include/php/Zend/zend_extensions.h: No such file or directory
Configuring for:
PHP Api Version:
Zend Module Api No:
Zend Extension Api No:
building in /private/var/tmp/pear/temp/pear-build-rootvAIHaa/xdebug-2.9.4
running: /private/var/tmp/pear/temp/xdebug/configure --with-php-config=/usr/bin/php-config
checking for grep that handles long lines and -e... /usr/bin/grep
checking for egrep... /usr/bin/grep -E
checking for a sed that does not truncate output... /usr/bin/sed
checking for cc... cc
checking whether the C compiler works... yes
checking for C compiler default output file name... a.out
checking for suffix of executables...
checking whether we are cross compiling... no
checking for suffix of object files... o
checking whether we are using the GNU C compiler... yes
checking whether cc accepts -g... yes
checking for cc option to accept ISO C89... none needed
checking how to run the C preprocessor... cc -E
checking for icc... no
checking for suncc... no
checking whether cc understands -c and -o together... yes
checking for system library directory... lib
checking if compiler supports -R... no
checking if compiler supports -Wl,-rpath,... yes
checking build system type... x86_64-apple-darwin19.2.0
checking host system type... x86_64-apple-darwin19.2.0
checking target system type... x86_64-apple-darwin19.2.0
checking for PHP prefix... /usr
checking for PHP includes... -I/usr/include/php -I/usr/include/php/main -I/usr/include/php/TSRM -I/usr/include/php/Zend -I/usr/include/php/ext -I/usr/include/php/ext/date/lib
checking for PHP extension directory... /usr/lib/php/extensions/no-debug-non-zts-20180731
checking for PHP installed headers prefix... /usr/include/php
checking if debug is enabled... no
checking if zts is enabled... no
checking for re2c... no
configure: WARNING: You will need re2c 0.13.4 or later if you want to regenerate PHP parsers.
checking for gawk... no
checking for nawk... no
checking for awk... awk
checking if awk is broken... no
checking whether to enable Xdebug support... yes, shared
checking whether to enable Xdebug developer build flags... no
checking Check for supported PHP versions... supported (7.3.9)
checking for gettimeofday... yes
checking for ANSI C header files... yes
checking for sys/types.h... yes
checking for sys/stat.h... yes
checking for stdlib.h... yes
checking for string.h... yes
checking for memory.h... yes
checking for strings.h... yes
checking for inttypes.h... yes
checking for stdint.h... yes
checking for unistd.h... yes
checking netinet/in.h usability... yes
checking netinet/in.h presence... yes
checking for netinet/in.h... yes
checking poll.h usability... yes
checking poll.h presence... yes
checking for poll.h... yes
checking sys/poll.h usability... yes
checking sys/poll.h presence... yes
checking for sys/poll.h... yes
checking for cos in -lm... yes
checking for ld used by cc... /Library/Developer/CommandLineTools/usr/bin/ld
checking if the linker (/Library/Developer/CommandLineTools/usr/bin/ld) is GNU ld... no
checking for /Library/Developer/CommandLineTools/usr/bin/ld option to reload object files... -r
checking for BSD-compatible nm... /usr/bin/nm -B
checking whether ln -s works... yes
checking how to recognize dependent libraries... pass_all
checking dlfcn.h usability... yes
checking dlfcn.h presence... yes
checking for dlfcn.h... yes
checking the maximum length of command line arguments... 196608
checking command to parse /usr/bin/nm -B output from cc object... ok
checking for objdir... .libs
checking for ar... ar
checking for ranlib... ranlib
checking for strip... strip
checking for dsymutil... dsymutil
checking for nmedit... nmedit
checking for -single_module linker flag... yes
checking for -exported_symbols_list linker flag... yes
checking if cc supports -fno-rtti -fno-exceptions... yes
checking for cc option to produce PIC... -fno-common
checking if cc PIC flag -fno-common works... yes
checking if cc static flag -static works... no
checking if cc supports -c -o file.o... yes
checking whether the cc linker (/Library/Developer/CommandLineTools/usr/bin/ld) supports shared libraries... yes
checking dynamic linker characteristics... darwin19.2.0 dyld
checking how to hardcode library paths into programs... immediate
checking whether stripping libraries is possible... yes
checking if libtool supports shared libraries... yes
checking whether to build shared libraries... yes
checking whether to build static libraries... no

creating libtool
appending configuration tag "CXX" to libtool
configure: creating ./config.status
config.status: creating config.h
running: make
/bin/sh /private/var/tmp/pear/temp/pear-build-rootvAIHaa/xdebug-2.9.4/libtool --mode=compile cc   -I. -I/private/var/tmp/pear/temp/xdebug -DPHP_ATOM_INC -I/private/var/tmp/pear/temp/pear-build-rootvAIHaa/xdebug-2.9.4/include -I/private/var/tmp/pear/temp/pear-build-rootvAIHaa/xdebug-2.9.4/main -I/private/var/tmp/pear/temp/xdebug -I/usr/include/php -I/usr/include/php/main -I/usr/include/php/TSRM -I/usr/include/php/Zend -I/usr/include/php/ext -I/usr/include/php/ext/date/lib -I/private/var/tmp/pear/temp/xdebug/src -I/private/var/tmp/pear/temp/pear-build-rootvAIHaa/xdebug-2.9.4/src  -DHAVE_CONFIG_H  -g -O2   -c /private/var/tmp/pear/temp/xdebug/xdebug.c -o xdebug.lo
mkdir .libs
 cc -I. -I/private/var/tmp/pear/temp/xdebug -DPHP_ATOM_INC -I/private/var/tmp/pear/temp/pear-build-rootvAIHaa/xdebug-2.9.4/include -I/private/var/tmp/pear/temp/pear-build-rootvAIHaa/xdebug-2.9.4/main -I/private/var/tmp/pear/temp/xdebug -I/usr/include/php -I/usr/include/php/main -I/usr/include/php/TSRM -I/usr/include/php/Zend -I/usr/include/php/ext -I/usr/include/php/ext/date/lib -I/private/var/tmp/pear/temp/xdebug/src -I/private/var/tmp/pear/temp/pear-build-rootvAIHaa/xdebug-2.9.4/src -DHAVE_CONFIG_H -g -O2 -c /private/var/tmp/pear/temp/xdebug/xdebug.c  -fno-common -DPIC -o .libs/xdebug.o
/private/var/tmp/pear/temp/xdebug/xdebug.c:25:10: fatal error: 'php.h' file not found
#include "php.h"
         ^~~~~~~
1 error generated.
make: *** [xdebug.lo] Error 1
ERROR: `make' failed

Can someone enlighten me what is the problem? Feel free to ask me to provide more information.

Answer 1

The Problem

The main problem is that Apple removed /usr/include in macOS Catalina, which had been the location for any C header file and still is on most any *NIX system. Attempting to install anything that relies on header files being within that specific location will fail miserably. The solution is to compile Xdebug manually, specifying the actual location of the header files, which are still provided by Xcode, just in an entirely different place.

Install Xcode

1) Download Xcode

2) Open Xcode, agree to terms if prompted, then quit.

3) Once installed open up Terminal:

$ xcode-select --install

4) Verify the SDK is found.

$ xcrun --show-sdk-path

It should look similar to the path below; you might need to edit the path accordingly later on:

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

Manually Compile Xdebug

As of this moment version 2.9.4 seems to be the latest, so we'll clone that version to compile.

$ git clone https://github.com/xdebug/xdebug.git
$ cd xdebug
$ git tag -l
$ git checkout tags/2.9.4

phpize

Next we need to make a copy phpize and then edit the include path:

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

Find this line (Control + W):

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

Replace it with this line:

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

Run phpize:

$ ./phpize

Correct output looks similar to this:

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

Configure & build

$ ./configure --enable-xdebug

After that's finished run make with the SDK location defined as compiler flags. Use 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"

There maybe warnings - just ignore it for now. Finally, run:

$ make install

This command will fail because it can't move the extension to the right place; SIP prevents it. We'll take care of moving it manually at the next step. make install is still required as it codesigns the *.so file.

Once make install has been run (and fails), we can move the executable:

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

Now edit the PHP configuration (php.ini) to enable Xdebug:

$ sudo nano /etc/php.ini

At the bottom add the following:

[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 apache:

$ sudo apachectl restart

Finally test everything went fine:

$ php -i | grep "xdebug support"

_{Notes: Thanks to Louis Charette for researching and finding a solution to this issue.}

↳ Installation of Xdebug on MacOS Catalina 10.15