Mac Catalina Install Xdebug

Question

I\'ve been struggling to get xdebug to work all day. I have tried a complete reinstall of homebrew, cleared out php and installed the newest version, reinstalled apache (fo

Answer 1

Ok, I got this working, thanks to Derek's help. Here is what I did for a full Mac PHP Development setup:

0) Install prerequisite software if not already installed (homebrew, xcode, etc)

Xcode command line tools:

$ xcode-select --install

Homebrew:

    $ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
Catalina Required Libraries:

Catalina Required Libraries:

 $ brew install openldap libiconv

1) Completely uninstall php, httpd (apache), and delete xdebug files (if you had them already installed):

$ brew update
$ brew upgrade
$ brew cleanup
$ brew list | grep php

Find whatever versions of php you have installed based on the brew list command then uninstall them, e.g.:

brew uninstall --force php72

Clean out any old php configurations

rm -Rf /usr/local/etc/php/*

2) Install Apache

If you already have the built-in Apache running, it will need to be shutdown first, and any auto-loading scripts removed:

$ sudo apachectl stop
$ sudo launchctl unload -w /System/Library/LaunchDaemons/org.apache.httpd.plist 2>/dev/null

Install apache:

$ brew install httpd

Setup Apache to autostart:

$ sudo brew services start httpd

You should now be able to go to http://localhost:8080 and see an "It Works" message.

3) Configure Apache

Using your favorite text editor, open /usr/local/etc/httpd/httpd.conf

Find the line that says Listen 8080 and change it to Listen 80

If you want, change to default directory of where you serve your websites from. Search for the term DocumentRoot and change the value to where you want. I used:

/Library/WebServer/Documents

but you can put it anywhere you like (such as /Users/your_user/Sites for example)

You also need to change the tag reference right below the DocumentRoot line. This should also be changed to point to your new document root also:

 /Library/WebServer/Documents

In that same block you will find an AllowOverride setting, this should be changed to:

# AllowOverride controls what directives may be placed in .htaccess files.
# It can be "All", "None", or any combination of the keywords:
#   AllowOverride FileInfo AuthConfig Limit
#
AllowOverride All

Also we should now enable mod_rewrite which is commented out by default. Search for mod_rewrite.so and uncomment the line by removing the leading #:

LoadModule rewrite_module lib/httpd/modules/mod_rewrite.so

Change the user and group to match your currently logged in user:

User your_user
Group staff

Change the servername to localhost

Save the file.

Restart Apache to ensure your changes take effect:

$ sudo apachectl -k restart

3) Install PHP

I installed php 7.2, even though it's not the latest, simply because my hosting site and wordpress uses php 7.2 and I want to integrate my php application with my wordpress site.

$ brew install php@7.2

Once php is installed, go back to your httpd.conf file and add the following line:

LoadModule php7_module /usr/local/opt/php@7.2/lib/httpd/modules/libphp7.so

below the previously uncommented LoadModule rewrite _module from the last step.

Also you must set the Directory Indexes for PHP explicitly, so search for this block:

<IfModule dir_module>
    DirectoryIndex index.html
</IfModule>

Copy and replace it with this:

<IfModule dir_module>
    DirectoryIndex index.php index.html
</IfModule>

<FilesMatch \.php$>
    SetHandler application/x-httpd-php
</FilesMatch>

Save the file and restart the apache server again:

$ sudo apachectl -k restart

4) Validate the php installation

Simply create a file called info.php in your Sites/ folder you created earlier with this one-liner.

echo "<?php phpinfo();" > ~/Sites/info.php

Point your browser to http://localhost/info.php and you should see a PHP information page.

Homebrew should have added its preferred /usr/local/bin and /usr/local/sbin to your path as part of its installation process. Quickly test this by typing:

$ echo $PATH
/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Library/Apple/usr/bin:/Library/Apple/bin

If you don't see this, you might need to add these manually to your path. Depending on your shell you're using, you may need to add this line to ~/.profile, ~/.bash_profile, or ~/.zshrc:

export PATH=/usr/local/bin:/usr/local/sbin:$PATH

5) Install Xdebug.

If the command:

$ pecl install xdebug

Fails due to the phpize not returning the correct information, or it's trying to write to folders it cannot, or it cannot find php.h, etc, as it did for me and what started this post, try the following:

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 it doesn't, install them using the command listed in step 0.

Now create a new folder in your home folder for phpize:

$ mkdir ~/php-private/

And copy the following file to it:

$ cp /usr/bin/phpize ~/php-private/

Open a text editor, and create a file with the following patch code:

--- /usr/bin/phpize 2019-09-11 02:46:18.000000000 +0200
+++ ./phpize    2019-12-26 23:10:32.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"

Save that file as phpize-catalina.patch in your new php-private folder (be sure to cd in to that folder too).

Next patch your new copy of phpize:

$ patch ~/php-private/phpize < phpize-catalina.patch    

Next, download the latest source files of xdebug, for me it was 2.9.0

$ git clone git://github.com/xdebug/xdebug.git

That should have downloaded all the source files to the ~/xdebug path. Change directories to this path.

$ cd ~/xdebug

Now run the phpize file we patched:

$ ~/php-private/phpize

You should see the following output:

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

If you receive the error:

Cannot find autoconf. Please check your autoconf installation and the
$PHP_AUTOCONF environment variable. Then, rerun this script.

It means you do not have autoconf installed. Try:

$ brew install autoconf

Once you receive the above output of phpize, configure and install xdebug:

./configure --with-php-config=/usr/local/opt/php@7.2/bin/php-config

This should use the php config that you installed via homebrew in step 3.

Now build the extension:

$ make

Now install it:

$ make install

You should see something like:

Installing shared extensions:     /usr/local/Cellar/php@7.2/7.2.26/pecl/20170718/

  +----------------------------------------------------------------------+
  |                                                                      |
  |   INSTALLATION INSTRUCTIONS                                          |
  |   =========================                                          |
  |                                                                      |
  |   See https://xdebug.org/install.php#configure-php for instructions  |
  |   on how to enable Xdebug for PHP.                                   |
  |                                                                      |
  |   Documentation is available online as well:                         |
  |   - A list of all settings:  https://xdebug.org/docs-settings.php    |
  |   - A list of all functions: https://xdebug.org/docs-functions.php   |
  |   - Profiling instructions:  https://xdebug.org/docs-profiling2.php  |
  |   - Remote debugging:        https://xdebug.org/docs-debugger.php    |
  |                                                                      |
  |                                                                      |
  |   NOTE: Please disregard the message                                 |
  |       You should add "extension=xdebug.so" to php.ini                |
  |   that is emitted by the PECL installer. This does not work for      |
  |   Xdebug.                                                            |
  |                                                                      |
  +----------------------------------------------------------------------+

Now you need to add the extension to your php.ini file. Use your favorite editor to modify /usr/local/etc/php/7.2/php.ini (don't forget sudo when opening your text editor) and add this to the very bottom:

[xdebug]
zend_extension=/usr/local/Cellar/php@7.2/7.2.26/pecl/20170718/xdebug.so
xdebug.remote_enable=1
xdebug.remote_host=localhost
xdebug.remote_handler=dbgp
xdebug.remote_port=9000

Note, all you really need to add is the zend_extension line but in order to have it work with Eclipse I use the remote enabled flags along with the other settings listed there.

Finally, restart apache:

$ sudo apachectl -k restart

And then when you refresh the info.php page you created earlier you should see lines for xdebug in the configuration. Something like:

succesful xdebug validation

6) Finally, for my complete PHP mac development setup, I installed the latest version of eclipse for php (from their website) as well as SQL Server (using homebrew). You can google how to install those as they are pretty straightforward.

Answer 2

Each error has a different cause.

First of all, your sudo pecl install is generally the right way of installing Xdebug, because, as you've found you can set the installation directory with pecl config-set.

However, the pecl/pear version that you are running, is likely for an old version of PHP. Because PHP does change once in a while, the pecl tool needs to be updated too. For PHP 7.2, I run pecl version 1.10.9 (you can check with pecl -V). I would think that the one you're running is quite a bit older. Generally you can update pear/pecl by using pear upgrade pear, but you will likely run into an unwritable directory problem again.

Secondly, sudo make install to fails because it is trying to write into an unwritable directory (/usr/lib/php/extensions/no-debug-non-zts-20180731/). If you know what the right directory is (check with php -i | grep extensions), you can just copy it into that directory yourself. After the make stage, there should be a xdebug.so in the modules directory within the Xdebug source tree.

The "official" way to solve the latter problem is to use the --with-php-config option to Xdebug's ./configure line, where you can specify the one that you want to use for Xdebug with something like: ./configure --with-php-config=/usr/local/opt/php@7.2/bin/php-config (but check the paths, as I don't have a Mac set up here). This should then pick up the right extensions directory, and sudo make install should work.

Answer 3

Note you can follow this answer if you want to install Xdebug natively on MacOS, without Homebrew.