Install PHP 7.3 + xdebug on MacOS Catalina (with homebrew)

Homebrew have relocated “php” formulas and renamed “php71” into “php@7.1” in 2018 making it quite difficult to and also removing extensions (such as xdebug) from brew. 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! MacOS Catalina comes with PHP 7.3 preinstalled! Check out my other article about PHP development with built-in PHP on macOS.

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

If you run into problems, I suggest you to clean up anything php-related first.

Also save your /usr/local/etc/php/7.*/conf.d folders.

Set up PHP

Install latest version of PHP:

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.

I also recommend installing composer from homebrew:

Now we can test the setup with ATK UI framework:

For the PHP file, type the following:

Save file and in the command-line run:

Finally navigate to and you should see:

For more information on what you can do with ATK UI, see

Setting up php-fpm with nginx

If you need to make use of beautiful URLs or some other web-server features you might need nginx or apache. To set up nginx with php-fpm, you would need to run:

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

Installing extensions

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

I have noticed and reported a bug in php formula which creates broken link in /usr/local/lib/php/pecl.

If you see error you might need to fix it:

You may also check out/usr/local/Cellar/php/7.2.8/lib/php/ . Compare with output of “php -i | grep pecl”

Installing and running older PHP versions

(Note: Homebrew removes unsupported PHP versions, if you need something really old, get binaries from

Sometimes you want to test your software against older PHP.

Here is how to set it up PHP7.2 (thanks Mike):

Here you can run phpunit with older PHP version:

To switch default PHP version entirely:

Next, lets switch back to latest PHP:

PHPStorm can be configured with multiple PHP versions.

Few final tips

By default your PHP file (located in /usr/local/etc/php/7.*/php.ini) is shared between command-line PHP and PHP-FPM. I recommend that you make copy of that file into php-fpm-fcgi.ini which will then be used by “php-fpm” SAPI.

You can enable xdebug extention in this file and remove it from php.ini to speed up your unit tests.

London based Web Developer, DevOps, Author of