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.
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
xdebug-toggle is handy! Follow install and usage instructions from its README.md, but here is a snippet:
curl -L https://raw.githubusercontent.com/w00fz/xdebug-osx/master/xdebug-toggle > ~/Dropbox/bin/xdebug-toggle
chmod +x ~/Dropbox/bin/xdebug-toggle
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.
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.
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.
- 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
- New Terminal window so everything's loaded afresh
php --ini
should mention parsing yourext-xdebug.ini
filephp -v
should mention Xdebug's version if it's runningxdebug-toggle off
should restart PHP- try
php --ini
to confirmext-xdebug.ini
is no longer included xdebug-toggle on
if you want to re-enable Xdebug
brew install composer
is easy
Update your .zschrc as follows:
alias composer='/usr/local/var/homebrew/linked/composer/bin/composer'
A)
- Preferences > Languages & Frameworks > PHP > CLI Interpreter > '...' to the far right
- Add New (I named mine "Homebrew Linked")
- PHP Executable:
/usr/local/var/homebrew/linked/php/bin/php
B)
- Preferences > Languages & Frameworks > PHP > Composer
- 'composer' executable:
/usr/local/var/homebrew/linked/composer/bin/composer
C)
- Preferences > Languages & Frameworks > PHP > Debug
- Using port 9001 helps avoid any potential conflicts with PHP-FPM binding on port 9000 by default
- Check/Uncheck boxes as per this screenshot:
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:
- https://mark.shropshires.net/blog/how-reinstall-homebrew-php-after-move-homebrewphp-homebrewcore
- https://javorszky.co.uk/2018/05/03/getting-xdebug-working-on-php-7-2-and-homebrew/
- https://getgrav.org/blog/macos-sierra-apache-upgrade-homebrew
- https://gist.github.com/ankurk91/22e4a07be552790a9d6a063ee1bace05
- https://www.farces.com/wikis/naked-server/php/homebrew-php-extensions/
- https://www.farces.com/wikis/naked-server/php/configure-php-ini/
- https://joostvanveen.com/a-30/installing-php-extensions-and-services-with-pecl-and-homebrew
- https://pixelfear.com/blog/xdebug-laravel-valet-phpstorm-composer
This guide came from here (synced so whichever is your preference):