cliff
10/23/2019 - 11:14 PM

Install PHP with Xdebug and Composer via Homebrew on Mac OS X Catalina (October 23, 2019)

ext-xdebug.ini
content_copyfile_download
[xdebug]
# Using https://github.com/w00fz/xdebug-osx/ so don't add `zend_extension` entry, as it would be duplicate
# https://xdebug.org/docs/all_settings
xdebug.remote_port=9001
xdebug.remote_enable=1
xdebug.remote_autostart=1
xdebug.remote_connect_back=1
xdebug.var_display_max_depth=-1
xdebug.var_display_max_children=-1
xdebug.var_display_max_data=-1
instructions.md
content_copyfile_download
  • Rendered
  • Source

1) Fresh Homebrew PHP to start

Before we get started, see where PHP is loading from for reference: which php will be /usr/local/bin/php if from native Mac OS X instead of Homebrew.

If you're a pre-existing Homebrew PHP user, follow this guide to fully uninstall all your past stuff.

2) Install latest PHP version via Homebrew:

Make sure ready to get started: brew doctor

If good, then install latest version of PHP: brew install php

After success, add Homebrew's linked (i.e. currently running) PHP version in your .zshrc

# PHP from the currently linked Homebrew PHP version
export BREW_PHP=/usr/local/var/homebrew/linked/php/bin
export PATH="$BREW_PHP:$PATH":"~/Dropbox/bin":/usr/local/bin

In a new terminal window, which php should now return /usr/local/var/homebrew/linked/php/bin/php

3) Install `xdebug-toggle

xdebug-toggle is handy! Follow install and usage instructions from its README.md, but here is a snippet:

Quick Install (to my Dropbox's bin folder)

  1. curl -L https://raw.githubusercontent.com/w00fz/xdebug-osx/master/xdebug-toggle > ~/Dropbox/bin/xdebug-toggle
  2. chmod +x ~/Dropbox/bin/xdebug-toggle

Usage

xdebug-toggle                            # outputs the current status
xdebug-toggle on                         # enables xdebug
xdebug-toggle off                        # disables xdebug
xdebug-toggle on|off --no-server-restart # toggles xdebug without restarting apache or php-fpm

In general, keep Xdebug disabled unless you need it. Running Codeception tests with it enabled will be extra slow, but at least now, with this setup, you can hit your breakpoints during it if running Xdebug.

4) Install Xdebug

Install the Zend Extension

Per https://xdebug.org/docs/install, run pecl install xdebug

Now find where PECL loads from: php -r "echo ini_get( 'extension_dir' );" should return something like /usr/local/lib/php/pecl/20180731 (the date is the API version installed; not important)

Go to this API folder and make sure xdebug.so is in it.

Add your .ini

Go to /usr/local/etc/php/7.3/conf.d (if 7.3 is the version Homebrew installed) and create your ext-xdebug.ini file (attached)

You'll need to copy this file to all other PHP versions you install via Homebrew, if any.

Gotchas

  • If your pecl dir is a symlink like mine somehow was or is otherwise not a directory, delete it, then try installing Xdebug again.
  • If still trouble might need to run one or both of these and try again:
    • brew install autoconf
    • brew install automake
  • If still trouble, reference https://xdebug.org/wizard and get the xdebug.so file to where it belongs

5) Confirm working

  1. New Terminal window so everything's loaded afresh
  2. php --ini should mention parsing your ext-xdebug.ini file
  3. php -v should mention Xdebug's version if it's running
  4. xdebug-toggle off should restart PHP
  5. try php --ini to confirm ext-xdebug.ini is no longer included
  6. xdebug-toggle on if you want to re-enable Xdebug

6) Install Composer via Homebrew

brew install composer is easy

Update your .zschrc as follows:

alias composer='/usr/local/var/homebrew/linked/composer/bin/composer'

7) Setup PhpStorm

A)

  1. Preferences > Languages & Frameworks > PHP > CLI Interpreter > '...' to the far right
  2. Add New (I named mine "Homebrew Linked")
  3. PHP Executable: /usr/local/var/homebrew/linked/php/bin/php

B)

  1. Preferences > Languages & Frameworks > PHP > Composer
  2. 'composer' executable: /usr/local/var/homebrew/linked/composer/bin/composer

C)

  1. Preferences > Languages & Frameworks > PHP > Debug
  2. Using port 9001 helps avoid any potential conflicts with PHP-FPM binding on port 9000 by default
  3. Check/Uncheck boxes as per this screenshot:

8) References

I wrote my own guide because none of these did 100% for me, but each were helpful in their own way and may be specific to any issues you encounter if my guide isn't 100% for you.

My guide...

  • uses the linked location to be as dynamic as possible so whenever I want to run sphp to switch PHP versions (other versions installed via Homebrew, which this guide did not cover), then I don't have to update my scripts or PhpStorm locations
  • uses my ~/Dropbox/bin (manually created) location so changes are versioned and synced between multiple computers and is in an easy-to-remember location if I ever want to make changes

In case they might help you:

Source

This guide came from here (synced so whichever is your preference):