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.

# 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.*/conf.d folders.

Set up PHP

Install latest version of PHP:

brew install php# note, that there are no longer options --with-httpd and
# --with-thread-safety.

This installs the following essential files:

  • /usr/local/opt/php/lib/httpd/modules/libphp7.so — 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:

brew install composer

Now we can test the setup with ATK UI framework:

mkdir test
cd test
composer require atk4/ui # may take a moment
nano test.php

For the PHP file, type the following:

<?php
include 'vendor/autoload.php';
$app = new atk4\ui\App('PHP-test');
$app->initLayout('Centered');
$app->add(['Label', 'Your PHP Version:', 'big blue', 'detail'=>phpversion()]);

Save file and in the command-line run:

php -S 127.0.0.1:8080

Finally navigate to http://127.0.0.1:8080/test.php and you should see:

You have just wrote a small PHP app!

For more information on what you can do with ATK UI, see https://github.com/atk4/ui/

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:

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

Here is my server section from /usr/local/etc/nginx/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_pass 127.0.0.1:9000;
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 which creates broken link in /usr/local/lib/php/pecl.

$ ls /usr/local/lib/php/pecl/201*/
opcache.a opcache.so xdebug.so

If you see error you might need to fix it:

cd /usr/local/lib/php
rm pecl
ln -s . pecl

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 https://php-osx.liip.ch)

Sometimes you want to test your software against older PHP.

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

brew install php@7.2
$(brew --prefix php@7.2)/bin/pecl install --force xdebug
$(brew --prefix php@7.2)/bin/php -S 127.0.0.1:8080

Here you can run phpunit with older PHP version:

$(brew --prefix php@7.2)/bin/php vendor/bin/phpunit

To switch default PHP version entirely:

php unlink php
php link php@7.2
php --version

Next, lets switch back to latest PHP:

brew unlink php@7.2
brew link 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.

Written by

London based Web Developer, DevOps, Author of https://agiletoolkit.org.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store