Xdebug for Mac OS X PHP
Tags: php
Published: 2019-10-07 12:35:46

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](https://xdebug.org/download.php) 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](https://jimfrenette.com/2018/12/xdebug-for-mac-os-x-php/)