Installation of Xdebug on MacOS Catalina 10.15

Question

I tried to install Xdebug on OS X 10.15 and run into following problem:

/private/tmp/pear/install/xdebug/xdebug.c:25:10: fatal error: 'php.h' file not found

I tried to fix the problem like described here: Installing xdebug on MacOs Mojave - 'php.h' file not found

Unfortunately the header files cannot be found in this directory: /Library/Developer/CommandLineTools/Packages

Any ideas where I can get the current header files for OS X 10.15?

Louis Charette · Accepted Answer · 2021-01-26T13:36:14.170

Update

For anyone that just want xdebug support on MacOS, most of the instructions in this answer are not necessary when using the built-in version of PHP. Before doing anything, you should check if xdebug.so already exists in /usr/lib/php/extensions/no-debug-non-zts-20180731/, which should be there by default. If so, you can skip to the Enabled support in PHP portion of this answer.

Using Homebrew is also an acceptable solution for you (and can also prevent other issues).

For anyone else looking to actually build binaries on MacOS and get the header error, the full answer is for you. It also answer OP question directly. Note building xdebug from source code and actually trying to use that version of xdebug.so with the build-in PHP should end up in a "code signature" error. As described here and here, the only real solution would be to compile and use you own instance of PHP instead of the built-in one. In any situation, using Homebrew would be easier.

tl;dr

Apple decided to remove headers file in /usr/include and the macOS_SDK_headers_for_macOS_10.14.pkg package. To install Xdebug, you'll have to manually compile Xdebug with the correct reference in both phpize and make.

For more details, I wrote a blog article about the issue and the solution

Original Answer:

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.

First, make sure Xcode is installed, including the command line tools. The following command will display the location of the default SDK :

$ xcrun --show-sdk-path
/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk

The header you'll want (php.h) will then be in /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/php/main.

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 :

make CPPFLAGS='-I/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/php -I/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/php/main -I/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/php/TSRM -I/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/php/Zend -I/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/php/ext -I/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/php/ext/date/lib'

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.

Enabled support in PHP

Next, we move the executable somewhere safe. I use /usr/local/php/extensions.

sudo mkdir -p /usr/local/php/extensions
sudo cp /usr/lib/php/extensions/no-debug-non-zts-20180731/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.

Note: A more complete fix would be to edit the result of php-config --include-dir, which returns /usr/include/php. That would make any installation find the necessary header files without having to manually edit files or compiler flags.

Most valuable answer! This should be marked as correct! Thank you sir! — eltomato, Nov 10 '19 at 11:57
This is the best way to resolve the issue. It worked for me. Thanks, Louis — Raja Mohammed, Dec 03 '19 at 07:03
For PHP 7.4 support, you need to install XDebug 2.9 (not 2.7.2). Just follow [these installation instructions](https://github.com/xdebug/xdebug/tree/xdebug_2_9) and after `make install` do all the steps of "Enabled support in PHP" chapter of this post. Keep in mind that you might have `php.ini` file in different location. Run `php --ini` to figure out where and edit the one that is being used instead. — Dejv, Jan 07 '20 at 07:30
I was good until the `./configure` command. I keep getting a `no such file or directory: ./configure`. Anyone else run into this or am I just the lucky one? :D — cbloss793, Feb 25 '20 at 21:09
@LouisCharette I looked over the instructions again and aren't I supposed to just be in the xdebug folder to run the configure command? — cbloss793, Feb 26 '20 at 16:19
@cbloss793 yes, eveything have to be ran inside the `xdebug` folder after you clone XDebug from Git. — Louis Charette, Feb 26 '20 at 21:18
Would simply copying the /usr/include folder from the SDK to /usr/include work here? I'm having this issue trying to install a different package from pecl. EDIT: Seems it wont let me create /usr/include at all, even with sudo :( — BoomShaka, Sep 02 '20 at 18:53
I get the following error on the `configure` step: `checking for grep that handles long lines and -e... configure: error: no acceptable grep could be found in ...` and then it lists my PATH. Is it possible I have a bad path? — Justin Hammond, Sep 17 '20 at 05:31
Indeed, but I would recommend using Brew on Big Sur : https://stackoverflow.com/questions/65064182/phpunit-always-output-no-tests-executed-on-macos-big-sur — Louis Charette, Jan 26 '21 at 13:42

score 1 · Answer 2 · answered Oct 15 '19 at 01:20

1

If you are using brew, I solve this by reinstalling php and re-linking:

brew reinstall php@7.3
brew link --overwrite php

answered Oct 15 '19 at 01:20

jamespsterling

33
5

Unfortunately brew stuff doesn't aways work as expected, depending on your versions. – jamespsterling Apr 14 '20 at 20:26

score 1 · Answer 3 · answered Dec 30 '20 at 10:38

I got an error when I tried to install xdebug in MacOS Catalina 10.15:

pecl install xdebug-3.0.1

Error:

/private/tmp/pear/install/xdebug/xdebug.c:25:10: fatal error: 'php.h' file not found

This is due to Apple decided to remove headers file in /usr/include, like you can see in other answer.

Then I added config to .bash_profile, executing these lines in console:

echo 'export PATH="/usr/local/opt/php@7.3/bin:$PATH"' >> ~/.bash_profile
echo 'export PATH="/usr/local/opt/php@7.3/sbin:$PATH"' >> ~/.bash_profile
export LDFLAGS="-L/usr/local/opt/php@7.3/lib"
export CPPFLAGS="-I/usr/local/opt/php@7.3/include"
source ~/.bash_profile

After that you can try to install xdebug again with pecl:

pecl install xdebug-3.0.1

Notes: Previously I have installed PHP 7.3 with "brew". You should adjust the php and xdebug version, in the above lines, adding the versions that you prefer.

As noted in the answer, this only applies if you already installed PHP using brew. If you're not using brew, you'll need to use the ehader files from Xcode. — Louis Charette, Jan 26 '21 at 13:23
Actually, `export PATH` should be required to get PHP itself running when using Homebrew, xdebug or not. Using brew "link" and "unlink" method should work too (and no need to edit `bash_profile` then). If Homebrew php version is in your path after a normal install, xdebug should install itself no problem. For brew link, see other answers or : https://getgrav.org/blog/macos-bigsur-apache-multiple-php-versions — Louis Charette, Jan 26 '21 at 14:07

score -1 · Answer 4 · answered Oct 10 '19 at 08:39

-1

I would recommend you use "brew" to install PHP, and then use the "pecl" tool that comes with the installed version of brew's PHP to install Xdebug.

answered Oct 10 '19 at 08:39

Derick

35,169
5
76
99

That's exactly what I did. When trying to install Xdebug with pecl I get the error mentioned above – Guenter Oct 10 '19 at 09:37
1

That means it's picking up the wrong pecl tool -- the one installed with your Mac. You need to make sure to use the brew provided one. – Derick Oct 10 '19 at 13:12
@Guenter did that hint solve your problem? I am having the same trouble and did `brew install php` but am still getting the same error. – Carter Pape Oct 12 '19 at 00:40
While this solution is acceptable, it doesn't technically answer the initial question. See my answer on how to solve the missing header issue. – Louis Charette Oct 16 '19 at 16:14
Or docker but there's other things that need it. pyenv has a dependency on it. – Hayden Dec 19 '19 at 19:31
Derick's answer is correct. Coincidentally, he wrote and maintains xdebug. @Derick - thank you! – James Bowler Jun 23 '20 at 20:31
sudo /usr/local/Cellar/php/7.4.9/bin/pecl install xdebug still gives the php.h error. That's using the brew installed one and it still dies... right? – BoomShaka Sep 02 '20 at 19:44

score -2 · Answer 5 · answered Feb 22 '20 at 10:41

-2

you can find detailed instructions with ready to use patches on this site: https://profilingviewer.com/installing-xdebug-on-catalina.html

answered Feb 22 '20 at 10:41

user24525

423
3
8

1

Answers that primarily reference an external site should include a summary of the information so that it becomes a primary source as well as a reference. This will help the answer to stand the test of time. – Louis Charette Apr 13 '20 at 18:39