Install PHP (with extensions) on MacOS using Homebrew

Problem Background

Recently, I wanted to include a new module ( visualception ) in my test automation project that is built on top of codeception. In order to successfully make it work, there was a requirement to have php-imagick extension already installed in your system.

Initial search showed that, in past you could have installed php-imagick extension using command like brew install php71-imagick , but this does not work any more of Homebrew updates . With the migration to Homebrew-core , the php formula has stopped taking over the role of PECL. So now for installation of php extensions (like imagick or x-debug) you have to use PECL .

Due to older php installations, I was getting lot of issues while trying to install php-imagick extension. Ultimately, I was able to resolve all the problems by installing PHP from scratch. In below, I have listed all the steps for fresh PHP installation.

1. Prerequisite Steps For First Time PHP-Installation

1.1 First install xcode-command-line tools by running below command in terminal. If any popup message appears during installation, that needs to be confirmed. For further details on xcode tools, you may check this link .

xcode-select --install

1.2 As we are going to do all PHP related installations through macOS package manager Homebrew. So next we need to set it up by running below command:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Installation process will will show several prompts and may also ask for mac password. This may take a few minutes. Once it is done, you can verify the installation was successful by running below commands:

brew --version # it will return the Homebrew installed version number like .. Homebrew 1.7.2

brew doctor # it will ensure everything is configured correctly and if something is wrong then give instructions to fix

2. Remove EXISTING PHP (homeBREW) INSTALLATIONS

2.1 Removing all PHP-Homebrew related installations

First run below brew commands to make sure brew is updated and has no configuration issues.

brew update  # updates brew itself
brew upgrade # upgrades all packages installed via brew
brew cleanup # by default, brew doesnot uninstall old versions. cleanup command will do the job
brew doctor  # Checks brew state and returns error, if there are any issues

If brew doctor or cleanup throws any errors then fix them as per instructions returned by brew-doctor or ask google 🙂

Now onto removing existing PHP-related installations (that were done by homebrew).

brew list | grep php # will show list of existing php installations done via homebrew
brew uninstall --force $x # where $x = value returned by above command (brew list | grep php)
rm -rf /usr/local/Cellar/php  # run to ensure php dir removed
rm ~/Library/LaunchAgents/homebrew.mxcl.php* # run to remove launch agents
sudo rm /Library/LaunchDaemons/homebrew.mxcl.php*

ps ax | grep php # checks php processes, if any still running then reboot

After above, again run brew cleanup and brew doctor to ensure everything working fine.

3. FINALLY… sTART WITH PHP INSTALLATION !

3.1 Run PHP Installation commands

brew install php # this command will install latest available version of php

Or if you want to install specific versions you may run commands like below

brew install [email protected] # these are version specific commands. run these if specific version required.
brew install [email protected] 
brew install [email protected]
brew install [email protected]

hash -r # update bash's internal paths

Once done with above, now verify thatyou are running the correct homebrew – PHP by running type php command. If it returns /usr/local/...anything.../php then it means you are  running homebrew-PHP. If it returns something like /usr/bin/php then it means you are running apple-supplied-PHP. In that case you need to fix paths, as we want to use homebrew-PHP! Finally run brew doctor to make sure everything is fine and no configuration errors are thrown.

3.2 Switching between PHP versions

If you have multiple php versions and want to switch between them, then you can do so by using brew link and brew unlink commands.

# Running below commands will switch php5.6 from php7.2
brew unlink [email protected]
brew link --force --overwrite [email protected]
brew doctor # to ensure all configs are fine
php -v # verify successful relinking done

# To again switch to php7.2 from php5.6 do below commands 
brew unlink [email protected]
brew link --force --overwrite [email protected]
brew doctor # to ensure all configs are fine
php -v # to verify successful relinking done

3.3 Install PHP extensions

As mentioned in start, php extensions such as php-imagick or php-xdebug which were previously installed by commands like ( brew install php53-imagick ) now should be installed by PECL (for details on PECL check this link ). Below are example commands for installation of xdebug and imagick extension.

pecl install xdebug
pecl install imagick

Now you may run php -v to verify php version and php -m to check enabled extensions.