(Re)installing PHP on Mac OS X

So you develop PHP on a Mac? Mebbe you, like me, you might have noticed a few deficiencies in the pre-loaded version of PHP on your computer. Maybe you, like me, prefer to use a newer version of PHP? Here’s how to …

Fix PHP on OS X

First you’ll need Homebrew1. If you’re not already using it, what are you waiting for?

tl;dr (just give me something to copy and paste)

If you’re impatient, copy and paste this gist into a Terminal.

Otherwise, you’ll want to use one of the following options to install the Homebrew formula for PHP 5.6

The default options work pretty great

brew tap homebrew/dupes
brew tap homebrew/versions
brew tap homebrew/homebrew-php
brew install php56

If you run into problems try updating Xcode Command Line Tools and re-installing

brew uninstall php56
brew cleanup
xcode-select --install # An "install" window will appear. Click "yes" on all the things.
brew install php56

By default this formula comes with MySQL and Apache

If you don’t want those, you can disable them with --without-mysql and --without-apache. Because Homebrew’s flexible like that.

But wait, there’s more!

This Homebrew formula can do PHP FPM, MSSQL and Postgres as well. As of the last time I checked, all of these options are available:

    Build without Opcache extension
    Disable auto-detection of Unicode encoded scripts (PHP 5.2 and 5.3 only)
    Build against apxs in Homebrew prefix
    Enable building of shared Apache 2.0 Handler module, overriding any options which disable apache
    Enable building of the CGI executable (implies --without-apache)
    Compile with debugging symbols
    Enable building of the fpm SAPI executable (implies --without-apache)
    Build with gmp support
    Include Curl support via Homebrew
    Include LibXSLT support via Homebrew
    Include OpenSSL support via Homebrew
    Include IMAP extension
    Include (old-style) libmysql support instead of mysqlnd
    Include MSSQL-DB support
    Include Oracle databases (requries ORACLE_HOME be set)
    Include PostgreSQL support
    Enable building of the phpdbg SAPI executable (PHP 5.4 and above)
    Build with thread safety
    Include Tidy support
    Build without bz2 support
    Remove MySQL/MariaDB support
    Build without Process Control support
    Build without PEAR
    install HEAD version

Using your fresh copy of PHP 5.6

You might have missed it, but Homebrew spit out a couple of caveats at the end of the install. The interesting bits probably looked something like this:

To enable PHP in Apache add the following to httpd.conf and restart Apache:
    LoadModule php5_module    /usr/local/opt/php56/libexec/apache2/libphp5.so

The php.ini file can be found in:

✩✩✩✩ PEAR ✩✩✩✩

If PEAR complains about permissions, 'fix' the default PEAR permissions and config:
    chmod -R ug+w /usr/local/Cellar/php56/5.6.0/lib/php
    pear config-set php_ini /usr/local/etc/php/5.6/php.ini

✩✩✩✩ Extensions ✩✩✩✩

If you are having issues with custom extension compiling, ensure that
you are using the brew version, by placing /usr/local/bin before /usr/sbin in your PATH:


PHP56 Extensions will always be compiled against this PHP. Please install them
using --without-homebrew-php to enable compiling against system PHP.

✩✩✩✩ PHP CLI ✩✩✩✩

If you wish to swap the PHP you use on the command line, you should add the following to ~/.bashrc,
~/.zshrc, ~/.profile or your shell's equivalent configuration file:

      export PATH="$(brew --prefix homebrew/php/php56)/bin:$PATH"

To have launchd start php56 at login:
    ln -sfv /usr/local/opt/php56/*.plist ~/Library/LaunchAgents
Then to load php56 now:
    launchctl load ~/Library/LaunchAgents/homebrew.mxcl.php56.plist

If you need to see the caveats again, run brew info php56

If you haven’t already, follow that advice

If you have any custom settings in your system-wide php.ini, copy them to the new one in /usr/local/etc/php/5.6.

Fix the PEAR config and upgrade

chmod -R ug+w `brew --prefix php56`/lib/php
pear config-set php_ini /usr/local/etc/php/5.6/php.ini

pear config-set auto_discover 1
pear update-channels
pear upgrade

You’ll need to install some PHP extensions now

Here’s a “Choose Your Own Adventure” moment. You can install packages via PECL, and have to reinstall them every time you update to a new minor PHP version, or you can install them via Homebrew.

I vote Homebrew.

Your needs will vary, but since this is my article I’ll just leave these here so I can copypaste them later:

brew install php56-mongo php56-memcache

Need gearman? How ‘bout that Twig extension? You can see a list of all (50 or so) available extensions by running

brew search php56-

If you didn’t go the brew install route for your extensions, or if you use extensions which aren’t available in Homebrew yet…

You’ll need to reinstall any additional PECL packages now (and whenever you update PHP). Like all good Homebrew setups, you won’t need sudo for PEAR anymore.

Because PEAR is now installed in the Homebrew prefix, you’ll need to reinstall all of your PEAR libraries as well

Before Composer supported global installs, this was a bit of a pain. Now, I don’t worry about it so much anymore.

After installing PEAR libraries with executables (like phpunit) you’ll need to get them into your path. Either add the PHP bin directory to your path (e.g. in ~/.bashrc):

export PATH="$(brew --prefix php56)/bin:$PATH"

… or symlink PHP binaries after running pear install ...:

brew unlink php56; brew link php56

Of course, there might be some gotchas

Offhand, I can think of one — In order to work with things like the Symfony2 console and PHPUnit, your new PHP should come before the pre-installed PHP in your $PATH. Check it like this:

which php

In my case, I see this:


If my $PATH were incorrect, I’d see this instead:


To fix it, you can add something like this to your .bashrc:

export PATH="$(brew --prefix)/bin:$PATH"

Now go build something cool!

  1. If you already have Homebrew installed, run brew update to make sure you have the latest hotness. 

  2. Remnants of older PEAR will keep the PHP installer from installing a new copy of PEAR, which, it turns out, is a Bad Thing.