How to install Xdebug on macOS 11 Big Sur (Xcode 12)
When you try to build xdebug on macOS Big Sur you will get errors like these:
xdebug.c:25:10: fatal error: 'php.h' file not found
#include "php.h"
^~~~~~~
1 error generated.
make: *** [xdebug.lo] Error 1
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:
/usr/include/php/main/php.h:33:10: fatal error: 'zend.h' file
not found
#include "zend.h"
^~~~~~~~
1 error generated.
make: *** [xdebug.lo] Error 1
/usr/include/php/Zend/../TSRM/TSRM.h:20:11: error:
'tsrm_config.h' file not found with <angled> include; use "quotes" instead
# include <tsrm_config.h>
^~~~~~~~~~~~~~~
"tsrm_config.h"
....
/usr/include/php/Zend/zend_virtual_cwd.h:24:10: fatal error:
'TSRM.h' file not found
#include "TSRM.h"
^~~~~~~~
2 errors generated.
make: *** [xdebug.lo] Error 1
Configure and build xdebug on macOS Big Sur
The reason for these errors is that the /usr/include folder is missing because Apple does not distribute this anymore.
But, you can work around this problem. Here is how:
First, you need to make sure that Xcode and the command line tools installed. Open a terminal window and run the following command to display the SDK path:
xcrun --show-sdk-path
This command should output something like this:
/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk
If not, install the command-line tools with executing:
xcode-select --install
and follow the instructions. After the installation is finished, start Xcode App to make sure the installation is done.
Now try to display the SDK-Path again:
xcrun --show-sdk-path
The php tools needed to compile an extension try to use this missing include folder. We will create a modified version of phpize and php-config which will use the includes from the macOS SDK. First we will copy phpize and php-config and then we will modify these copies with a patch.
We create a new folder in your home directory under /Users/YOUR-USERNAME with the name "php-private"..
mkdir ~/php-private/
Now copy phpize and php-config to php-private
cp /usr/bin/phpize ~/php-private/
cp /usr/bin/php-config ~/php-private/
Now determine which PHP version is installed on your system by executing
grep version= ~/php-private/php-config
You should get something like this with 7.3.22 or 7.3.24
version="7.3.22-(to be removed in future macOS)"
I have prepared two patches to simplify the process. Download the two files and save them in your Downloads folder.
Download the phpize patch phpize-bigsur.patch.zip and save it. The contents of the patch file for reference:
--- /usr/bin/phpize 2020-01-01 09:00:00.000000000 +0100
+++ ./phpize 2020-12-05 00:54:37.000000000 +0100
@@ -1,11 +1,12 @@
#!/bin/sh
# Variable declaration
+XCODE_SDK_ROOT=$(/usr/bin/xcrun --show-sdk-path)
prefix='/usr'
datarootdir='/usr/php'
exec_prefix="`eval echo ${prefix}`"
phpdir="`eval echo ${exec_prefix}/lib/php`/build"
-includedir="`eval echo ${prefix}/include`/php"
+includedir="`eval echo ${XCODE_SDK_ROOT}${prefix}/include`/php"
builddir="`pwd`"
SED="/usr/bin/sed"
For PHP 7.3.22 Download the php-config patch php-config-7.3.22-bigsur.patch.zip and save it.
For PHP 7.3.24 Download the php-config patch php-config-7.3.24-bigsur.patch.zip and save it.
The contents of the patch file for reference:
--- /usr/bin/php-config 2020-01-01 09:00:00.000000000 +0100
+++ ./php-config 2020-12-05 00:55:15.000000000 +0100
@@ -1,12 +1,12 @@
#! /bin/sh
-
+XCODE_SDK_ROOT=$(/usr/bin/xcrun --show-sdk-path)
SED="/usr/bin/sed"
prefix="/usr"
datarootdir="/usr/php"
exec_prefix="${prefix}"
version="7.3.22-(to be removed in future macOS)"
vernum="70322"
-include_dir="${prefix}/include/php"
+include_dir="${XCODE_SDK_ROOT}${prefix}/include/php"
includes="-I$include_dir -I$include_dir/main -I$include_dir/TSRM -I$include_dir/Zend -I$include_dir/ext -I$include_dir/ext/date/lib"
ldflags=" -L$SDKROOT/usr/lib -L$SDKROOT/usr/local/libressl/lib "
libs="-lresolv -lcrypto -lssl -lcrypto -lexslt -ltidy -lresolv -ledit -lncurses -lldap -llber -liconv -liconv -lpng -lz -ljpeg -lcrypto -lssl -lcrypto -lbz2 -lz -lcrypto -lssl -lcrypto -lm -lxml2 -lz -licucore -lm -lkrb5 -lcurl -lxml2 -lz -licucore -lm -lxml2 -lz -licucore -lm -lnetsnmp -lxml2 -lz -licucore -lm -lxml2 -lz -licucore -lm -lxml2 -lz -licucore -lm -lxml2 -lz -licucore -lm -lxml2 -lz -licucore -lm -lxml2 -lz -licucore -lm -lxslt -lxml2 -lz -licucore -lm "
Extract the compressed patch files.
PHP 7.3.22:
unzip ~/Downloads/phpize-bigsur.patch.zip -d ~/Downloads/
unzip ~/Downloads/php-config-7.3.22-bigsur.patch.zip -d ~/Downloads/
PHP 7.3.24:
unzip ~/Downloads/phpize-bigsur.patch.zip -d ~/Downloads/
unzip ~/Downloads/php-config-7.3.24-bigsur.patch.zip -d ~/Downloads/
Now we patching our copy of phpize and php-config
PHP 7.3.22:
patch ~/php-private/phpize < ~/Downloads/phpize-bigsur.patch
patch ~/php-private/php-config < ~/Downloads/php-config-7.3.22-bigsur.patch
PHP 7.3.24:
patch ~/php-private/phpize < ~/Downloads/phpize-bigsur.patch
patch ~/php-private/php-config < ~/Downloads/php-config-7.3.24-bigsur.patch
We are ready to compile xdebug
Create a working directory in your home folder. We will build xdebug here
mkdir ~/xdebug-install
Download xdebug from Xdebug.org and save in under Downloads.
Copy the archive to the working directory and extract it.
cp ~/Downloads/xdebug-3.0.1.tgz ~/xdebug-install
cd ~/xdebug-install
tar -xvzf xdebug-3.0.1.tgz
cd xdebug-3.0.1
Now, we run our patched phpize in the xdebug folder.
~/php-private/phpize
When everything went good, you get something like this:
Configuring for:
PHP Api Version: 20180731
Zend Module Api No: 20180731
Zend Extension Api No: 320180731
If so, you can skip the next part and continue with configuring and installing Xdebug.
Errors like these means, you need to install some requirements.
Configuring for:
PHP Api Version: 20180731
Zend Module Api No: 20180731
Zend Extension Api No: 320180731
Cannot find autoconf. Please check your autoconf installation and the
$PHP_AUTOCONF environment variable. Then, rerun this script.
If phpize prints lines like these, you need to install autoconf:
Cannot find autoconf. Please check your autoconf installation and the
$PHP_AUTOCONF environment variable. Then, rerun this script.
To install autoconf, execute the following commands:
#change back to our working directory
cd ~/xdebug-install
#dowload autoconf
curl -OL http://ftpmirror.gnu.org/autoconf/autoconf-2.69.tar.gz
#extract it, and change into the folder
tar xzf autoconf-2.69.tar.gz
cd autoconf-2.69
#now build and install it
./configure --prefix=/usr/local
make
sudo make install
#change back to the xdebug folder
cd ..
cd xdebug-3.0.1
Now run our patched phpize in the xdebug folder again.
~/php-private/phpize
Check the output, and if everything went good, continue.
Configuring for:
PHP Api Version: 20180731
Zend Module Api No: 20180731
Zend Extension Api No: 320180731
Configure and build xdebug:
Now we will find the full path to our patched php-config. This can be done like this:
echo ~/php-private/php-config
The output will something like:
/Users/YOUR-USERNAME/php-private/php-config
Replace "/Users/YOUR-USERNAME/php-private/php-config" with the output of the above command and configure xdebug by executing:
./configure --enable-xdebug --with-php-config=/Users/YOUR-USERNAME/php-private/php-config
In the output of configure you will see that the SDK path is being used:
...
checking for PHP prefix... /usr
checking for PHP includes... -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
checking for PHP extension directory... /usr/lib/php/extensions/no-debug-non-zts-20180731
checking for PHP installed headers prefix... /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/php
checking if debug is enabled... no
...
Now build the extension
make
We don't executing "make install" to install xdebug.so because the macOS System Integrity Protection (SIP) will not allow us to install xdebug to the /usr/lib/extensions folder. To workaround this, we install the extension under the /usr/local folder.
sudo mkdir -p /usr/local/php/extensions
sudo cp modules/xdebug.so /usr/local/php/extensions
Now edit your php.ini (usually under /etc/php.ini) to load the right xdebug. PHP searches for extensions in its default extension directory. Our xdebug resides outside of this directory, so we have to specify the full path:
zend_extension=/usr/local/php/extensions/xdebug.so
To test it, execute:
php -i | grep xdebug
The output should begin like this:
xdebug
xdebug support => enabled
....
Restart your apache web server to activate your changes
sudo apachectl restart