Install PHP 7.2 + xdebug on MacOS High Sierra (with homebrew July 2018)

There have been a lot of movements in Homebrew lately which have renamed “php71” into “php@7.1” and made it quite difficult to figure out how to install any extensions “such as xdebug”, so in this guide I’ll show you how to clean up all the older configuration and set up a clean environment. (Some more info on this approach)

DID YOU KNOW? You may not need PHP from Homebreew! Check out my other article about PHP development with built-in PHP 7.1 on masOS High Sierra.

Before you continue with this guide, make sure you have enough time to complete it fully. It will require you to clean things up before setting everything back up again.

Clean up

I suggest you to clean up anything php-related first.

# Will show you any php packages you've got. make not of that!
brew list | grep php
# Will uninstall any php packages you may have
brew list | grep php | while read x; do brew uninstall --force $x; done
# You may need to run this too
rm -rf /usr/local/Cellar/php
# Clean up Launch Agents
rm ~/Library/LaunchAgents/homebrew.mxcl.php*
sudo rm /Library/LaunchDaemons/homebrew.mxcl.php*
brew untap homebrew/php
brew cleanup
brew update
brew doctor # just to make sure you're all clean
ps ax | grep php
# if some PHP daemons are still runing, reboot.

Also save your /usr/local/etc/php/7.2/conf.d folder and rename it. Any extensions from there won’t work

Set up PHP

Install latest version of PHP:

brew install php
# note, that there are no longer options --with-httpd and
# --with-thread-safety. if you use them you get warnings:
# Warning: php: this formula has no --with-httpd option so it will be ignored!
# Warning: php: this formula has no --with-thread-safety option so it will be ignored!

This installs the following essential files:

  • /usr/local/opt/php/lib/httpd/modules/ — your apache module.
  • /usr/local/bin/php — your command line PHP.
  • /usr/local/sbin/php-fpm — your PHP-FPM binary.

Instructions to setting this up with Apache are also provided. See below on extensions.

Setting up php-fpm with nginx

If you wish to use nginx with php-fpm, you would need to run:

brew install nginx
sudo brew services brew start nginx # runs as root to use port 80
brew services start php

Here is my server section from nginx.conf (replace rw with your username)

server {
listen 80;
server_name localhost;
client_max_body_size 20M;
  root   /Users/rw/Sites/;
  location / {
index index.php index.html index.htm;
  location = /yourapp/ {
# Simpler version of mod_rewrite catch-all approach
    index index.php;
  location /otherapp/ {
# Actual URL rewriting
    rewrite ^/[^/]*/(.*) /otherapp/index.php?page=$1;
  location ~ \.php$ {
fastcgi_index index.php;
    # goes on same line:
fastcgi_param SCRIPT_FILENAME /Users/rw/Sites/$fastcgi_script_name;
    include        fastcgi_params;

Installing extensions

Extensions such as php-xdebug and php-mongodb have been removed and now should be installed from PECL:

pecl install xdebug
I have noticed and reported a bug in php formula and if it’s still not fixed, you may need to move your extension from: /usr/local/lib/php/pecl into /usr/local/Cellar/php/7.2.8/lib/php/ manually.

Installing and running older PHP versions

Sometimes you want to test your software against older PHP. Here is how to set it up PHP5.6:

brew unlink php
brew install php@5.6
brew link php@5.6 --force
# install the last version supported for php 5.6
pecl install xdebug-2.5.5
php --version

This wasn’t been able to locale extension for me initially, because it got installed into /usr/local/lib/php/pecl instead of /usr/local/Cellar/php@5.6/5.6.37/lib/php/

but after moving it into correct location it worked:

mv /usr/local/lib/php/pecl/20131226/ lib/php/20131226/

Next, lets switch back to latest PHP

brew unlink php@5.6
brew link php

You can still invoke php 5.6 from command-line like this:

/usr/local/Cellar/php@5.6/5.6.37/bin/php --version
PHP 5.6.37 (cli) (built: Jul 20 2018 08:26:50)
Copyright (c) 1997-2016 The PHP Group
Zend Engine v2.6.0, Copyright (c) 1998-2016 Zend Technologies
with Xdebug v2.5.5, Copyright (c) 2002-2017, by Derick Rethans
with Zend OPcache v7.0.6-dev, Copyright (c) 1999-2016, by Zend
# or run phpunit with older PHP
/usr/local/Cellar/php@5.6/5.6.37/bin/php vendor/bin/phpunit

Few final tips

Your .ini file is located in /usr/local/etc/php/7.2/php.ini. I recommend you to copy this file into php-fpm-fcgi.ini which will then be used by “php-fpm” SAPI. You can enable xdebug extention in this file and it will apply only to php-fpm.