Xdebug for Mac OS X PHP

Follow these instructions for PHP provided with Mac OS X to phpize Xdebug source, configure, build and install the PHP Xdebug extension.

• On Mac OS X Mojave, use the Xdebug extension included with the system in /usr/lib/php/extensions/no-debug-non-zts-20160303.

Download the latest version of Xdebug.

Verify that PHP is installed. e.g.,

php -v

# output
PHP 7.1.19 (cli) (built: Aug 17 2018 20:10:18) ( NTS )
Copyright (c) 1997-2018 The PHP Group
Zend Engine v3.1.0, Copyright (c) 1998-2018 Zend Technologies

Extract the downloaded Xdebug tarball as described in the earlier instructions above. e.g.,

cd ~/Downloads

mkdir xdebug
mv xdebug-2.6.1.tgz xdebug/

cd xdebug
tar xzf xdebug-2.6.1.tgz

Run phpize from within the extracted Xdebug source directory. e.g.,

cd xdebug-2.6.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:

If the Xcode commandline tools are not installed, phpize outputs missing include file messages. You can install the Xcode commandline tools using the CLI. e.g.,

xcode-select --install

If the Xcode commandline tools are already installed and/or you still get the missing include files message, force a reinstall of the commandline tools header files. e.g.,

sudo installer -pkg /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg -target /

Retry running phpize from within the extracted Xdebug source directory. e.g.,

phpize
Configuring for:
PHP Api Version:         20160303
Zend Module Api No:      20160303
Zend Extension Api No:   320160303

Configure Xdebug.

./configure

Build Xdebug.

make

Starting with OS X 10.11 El Capitan, system files and processes are protected with System Integrity Protection (SIP). Since /usr/lib/php/extensions write operations are not permitted with SIP enabled, install the Xdebug extension under the /usr/local. e.g.,

sudo mkdir -p /usr/local/php/extensions

sudo cp modules/xdebug.so /usr/local/php/extensions/

Update the /private/etc/php.ini file to load the Xdebug extension. e.g.,

...

;;;;;;;;;;;;;;;;;;;;;;
; Dynamic Extensions ;
;;;;;;;;;;;;;;;;;;;;;;

...

zend_extension=/usr/lib/php/extensions/no-debug-non-zts-20160303/xdebug.so

• If /private/etc/php.ini does not exist, PHP is using the default settings. Copy the /private/etc/php.ini.default sample configuration file to /private/etc/php.ini and update it to customize PHP settings.

Verify

php -i | grep xdebug

# expected output
xdebug
xdebug support => enabled
...

• If you get the following error message in the output, use the Xdebug extension provided with the system in /usr/lib/php/extensions/no-debug-non-zts-20160303

  Failed loading /usr/local/php/extensions/xdebug.so: dlopen(/usr/local/php/extensions/xdebug.so, 0x0009): code signature in (/usr/local/php/extensions/xdebug.so) not valid for use in process: mapped file has no cdhash, completely unsigned? Code has to be at least ad-hoc signed.

Remote Debugging

Enable remote debugging by adding the following xDebug settings at or near the bottom of the php.ini file.

...

[XDebug]
xdebug.remote_enable = 1
xdebug.remote_autostart = 1

Originally published at jimfrenette.com/2018/12/xdebug-for-mac-os-x-php