I recently needed to switch between PHP versions on my macOS environment to work on a legacy project. As usual, I’d forgotten how to do this, so I’ve decided to publish the steps for my own and other’s reference. The instructions below are for use with macOS 10.15 Catalina, and allow installation of PHP 5.6, 7.0, 7.1, 7.2, 7.3 & 7.4. You’ll need both Xcode Command Line Tools and Homebrew installed. 1.1 Install XCode Command Line Tools 1.2 Install Homebrew Homebrew is a package manager for macOS. It’s like Check that brew has installed: You can also run
As of writing, only PHP 7.2, 7.3 and 7.4 are maintained and supported by Homebrew. To install PHP 5.6, 7.0 & 7.1 we’ll need to ‘tap’ a repository for deprecated packages: Now, we can install all the available PHP versions: This may take a little time to install. Go make yourself a brew ☕️. Once installed, you can
switch between PHP versions by ‘linking’ and ‘unlinking’ in brew: You can combine There are a few open source projects that aim to automate this for you, if you prefer:1. Prerequisites
xcode-select --install
apt
on Ubuntu./usr/bin/ruby -e "$[curl -fsSL //raw.githubusercontent.com/Homebrew/install/master/install]"
$ brew --version
Homebrew 2.2.5
brew doctor
to check everything is good to go.2. Install Multiple PHP Versions
brew tap exolnet/homebrew-deprecated
brew install [email protected]
brew install [email protected]
brew install [email protected]
brew install [email protected]
brew install [email protected]
brew install [email protected]
# Switch from 7.4 to 5.6
brew unlink [email protected]
brew link [email protected] --force
brew unlink
and brew link
to swap between any installed version.Open Source Alternatives
I'm a PHP Developer based in UK, building modern PHP web applications and writing about everything I learn.
Part 1: macOS 11.0 Big Sur Web Development Environment
Developing web applications on macOS is a real joy. There are plenty of options for setting up your development environments, including the ever-popular MAMP Pro that provides a nice UI on top of Apache, PHP and MySQL. However, there are times when MAMP Pro has slow downs, or out of date versions, or is simply behaving badly due to its restrictive system of configuration templates and non-standard builds.
It is times like these that people often look for an alternative approach, and luckily there is one, and it is relatively straight-forward to setup.
In this blog post, we will walk you through setting up and configuring Apache 2.4 and multiple PHP versions. In the second blog post in this two-post series, we will cover MySQL, Apache virtual hosts, APC caching, and Xdebug installation.
10/31/2021 Added dynamic support for Apple Silicon and Intel homebrew paths
10/29/2021 Updated to reflect macOS 12.0 Monterey and removed PHP 5.6
11/27/2020 Updated to add some information on PHP 8.0
11/13/2020 Updated to reflect the
release of macOS 11.0 Big Sur
12/02/2019 Updated to reflect the latest release of PHP 7.4 and the removal of PHP 7.1 from Official tap
12/02/2019 Updated to reflect the latest release of PHP 7.4 and the removal of PHP 7.1 from Official tap
10/08/2019 Updated to reflect the release of macOS 10.5 Catalina
01/10/2019 Updated to add back PHP 5.6 and PHP
7.0 from and external deprecated keg
12/12/2018 Updated to reflect the latest release of PHP 7.3 and the removal of PHP 7.0 from Brew.
If you have followed this guide in the past with the Homebrew/php
tap, and are looking to upgrade to the new Homebrew/core
approach, then you should first clean-up your current installation by following our new
Upgrading Homebrew.
This guide is intended for experienced web developers. If you are a beginner developer, you will be better served using MAMP or MAMP Pro.
XCode Command Line Tools
If you don't already have XCode installed, it's best to first install the command line tools as these will be used by homebrew:
xcode-select --install
Homebrew Installation
This process relies heavily on the macOS package manager called Homebrew. Using the brew
command you can easily add powerful functionality to your mac, but first we have to install it. This is a simple process, but you need to launch your Terminal [/Applications/Utilities/Terminal
] application and then enter:
/bin/bash -c "$[curl -fsSL //raw.githubusercontent.com/Homebrew/install/master/install.sh]"
Just follow the terminal prompts and enter your password where required. This may take a few minutes.
If
this is a fresh install and you don't have your path setup properly, you can follow the installation "next steps" which are already customized for you, or you can manually add the following paths to your .bashrc
or .zshrc
:
eval "$[/opt/homebrew/bin/brew shellenv]"
Now you can test your installation to ensure you have installed brew
correctly, simply type:
brew --version
Homebrew 3.3.1
Homebrew/homebrew-core [git revision 1362c572e16; last commit 2021-10-29]
You should probably also run the following command to ensure everything is configured correctly:
brew doctor
It will instruct you if you need to correct anything.
Monterey Required Libraries
When installing fresh on Monterey, I ran into a few libraries that were missing when completing all the steps below. To make things easier, please simply run this now:
brew install openssl
Apache Installation
The latest macOS 12.0 Monterey comes with Apache 2.4 pre-installed, however, it is no longer a simple task to use this version with Homebrew because Apple has removed some required scripts in this release. However, the solution is to install Apache 2.4 via Homebrew and then configure it to run on the standard ports [80/443].
If you already have the built-in Apache running, it will need to be shutdown first, and any auto-loading scripts removed. It really doesn't hurt to just run all these commands in order - even if it's a fresh installation:
sudo apachectl stop
sudo launchctl unload -w /System/Library/LaunchDaemons/org.apache.httpd.plist 2>/dev/null
Now we need to install the new version provided by Brew:
brew install httpd
Without options, httpd
won't need to be built from source, so it
installs pretty quickly. Upon completion you should see a message like:
🍺 /opt/homebrew/Cellar/httpd/2.4.51: 1,660 files, 32.0MB
Now we just need to configure things so that our new Apache server is auto-started
brew services start httpd
You now have installed Homebrew's Apache, and configured it to auto-start with a privileged account. It should already be running, so you can try to reach your server in a browser by pointing it at //localhost:8080
, you should see a simple header that says "It works!".
Troubleshooting Tips
If you get a message that the browser can't connect to the server, first check to ensure the server is up.
ps -aef | grep httpd
You should see a few httpd processes if Apache is up and running.
Try to restart Apache with:
brew services restart httpd
You can watch the Apache error log in a new Terminal tab/window during a restart to see if anything is invalid or causing a problem:
tail -f /opt/homebrew/var/log/httpd/error_log
Apache is controlled via the brew services
command so some useful commands to use are:
brew services stop httpd
brew services start httpd
brew services restart httpd
Visual Studio Code
In past guides, I've always provided instructions to edit files using the default TextEdit
application that comes pre-installed. However, this is not what I use myself as it's a terrible editor and when testing my guide for Big Sur, I kept running into problems with encoding, finding line numbers etc. The better
solution is to simply install a better editor. So please install the amazingly versatile yet, 100% free, Visual Studio Code. It's available on Mac, Windows, and Linux, but right now we only care about the mac version.
We can make use of the HomeBrew and install VSCode and the accompanying code
CLI command in one shot with:
brew install --cask visual-studio-code
If you already have Visual Studio Code installed, you can easily create a code
symlink with:
ln -s /Applications/Visual\ Studio\ Code.app/Contents/Resources/app/bin/code /opt/homebrew/bin/code
Apache Configuration
Now that we have a working web server, we will want to do is make some configuration changes so it works better as a local development server.
In the latest version of Brew, you have to manually set the listen port from the default of 8080
to 80
, so we will need to edit Apache's configuration file /opt/homebrew/etc/httpd/httpd.conf
.
If you followed the instructions above you should be able to use Visual Studio Code to edit your files using the code
Terminal command. However, if you want to
use the default TextEditor application to perform edits, you can use the open -e
command followed by the path to the file.
code /opt/homebrew/etc/httpd/httpd.conf
Find the line that says
Listen 8080
and change it to 80
:
Listen 80
Next we'll configure it to use the to change the document root for Apache. This is the folder
where Apache looks to serve file from. By default, the document root is configured as /opt/homebrew/var/www
. As this is a development machine, let's assume we want to change the document root to point to a folder in our own home directory.
Search for the term DocumentRoot
, and you should see the following line:
DocumentRoot "/opt/homebrew/var/www"
Change this to point to your user directory where your_user
is the name of your user account:
DocumentRoot "/Users/your_user/Sites"
You also need to change the tag reference right below the DocumentRoot
line. This should also be changed to point to your new document root also:
In that same block you will find an
AllowOverride
setting, this should be changed as follows:
#
# AllowOverride controls what directives may be placed in .htaccess files.
# It can be "All", "None", or any combination of the keywords:
# AllowOverride FileInfo AuthConfig Limit
#
AllowOverride All
Also we should now enable mod_rewrite which is commented out by default. Search for mod_rewrite.so
and uncomment the line by removing the leading #
by pushing ⌘
+ /
on the line [this is a quick way to uncomment and comment a single or multiple lines:
LoadModule rewrite_module lib/httpd/modules/mod_rewrite.so
User & Group
Now we have the Apache configuration pointing to a Sites
folder in our home directory. One problem still exists, however. By default, apache runs as the user daemon
and group daemon
. This will cause permission problems when trying to access files in our home directory. About a third of the way down the httpd.conf
file there are two settings to set the User
and Group
Apache will run under. Change these to match your user account [replace your_user
with your real
username], with a group of staff
:
User your_user
Group staff
Servername
Apache likes to have a server name in the configuration, but this is disabled by default, so search for:
#ServerName www.example.com:8080
and replace it with:
ServerName localhost
Sites Folder
Now, you need to create a Sites
folder in the root of your home directory. You can do this in your terminal, or in Finder. In this new Sites
folder create a simple index.html
and put some dummy content in it like:
.My User Web Root
mkdir ~/Sites
echo "My User Web Root
" > ~/Sites/index.html
Restart apache to ensure your configuration changes have taken effect:
brew services stop httpd
brew services start httpd
If you receive an error upon restarting Apache, try removing the quotes around the DocumentRoot and Directory designations we set up earlier.
Pointing your browser to //localhost
should display your new message. If you have that working, we can move on!
Makes sure you remove the :8080
port we used earlier. Also, you might need to Shift
+ Reload
to clear the browser cache and pick up the new file.
Troubleshooting Non-Sudo httpd Services Start
I will be updating this section with more tips and things to try as I find solutions to common problems. Please hop on our #macos Discord Chat to get some "live" help.
This year, with macOS Big Sur, I've switched from
using sudo
to launch httpd
with root [even though it ran as the user/group defined in httpd.conf
], and for people who have upgraded from that version to this, there have been problems.
I ran into some problems myself but was able to get it working pretty easily, but others have reported more wide-spread problems. Please try these steps if your Apache is not starting when you use brew services start httpd
.
First, try to start apache directly with:
/opt/homebrew/bin/httpd -k start
This bypasses the brew services command and often prints out specific issues. If you have issues reported about not being able to write to log files, try removing all the current log httpd log files:
rm -Rf /opt/homebrew/var/log/httpd/*
Then try starting again.
If you have see a message saying something like Address already in use: AH00072: make_sock: could not bind to address
, try changing the Listen
config in httpd.conf
to:
Listen 0.0.0.0:80
PHP Installation
If you have existing PHP installations via Brew, you need to first cleanup your setup with our Upgrading Homebrew guide before continuing with this section.
Up until the end of March 2018, all PHP related brews were handled by Homebrew/php
tab, but that has been deprecated, so now we use what's available in the Homebrew/core
package. This should be a better maintained, but is a much less complete, set of packages.
PHP 7.0, and PHP 7.1 have been deprecated and
removed from Brew because they are out of support, and while it's not recommended for production, there are legitimate reasons to test these unsupported versions in a development environment. These versions also need to "built from source" in order to use the latest versions of icu4c
and openssl
.
Remember only PHP 7.2 through 8.1 are officially supported by Brew, but these also have to be built which is pretty slow. For the latest version of our guide we will use the new tap from @shivammahtur as there are many versions [including the latest PHP 8.1] pre-built.
brew tap shivammathur/php
We will proceed by installing various versions of PHP and using a simple script to switch between them as we need. Feel free to exclude any versions you don't want to install.
brew install shivammathur/php/[email protected]
brew install shivammathur/php/[email protected]
brew install shivammathur/php/[email protected]
brew install shivammathur/php/[email protected]
brew install shivammathur/php/[email protected]
brew install shivammathur/php/[email protected]
Also, you may have the need to tweak
configuration settings of PHP to your needs. A common thing to change is the memory settings or the date.timezone
configuration. The php.ini
files for each version of PHP are located in the following directories:
/opt/homebrew/etc/php/7.0/php.ini
/opt/homebrew/etc/php/7.1/php.ini
/opt/homebrew/etc/php/7.2/php.ini
/opt/homebrew/etc/php/7.3/php.ini
/opt/homebrew/etc/php/7.4/php.ini
/opt/homebrew/etc/php/8.0/php.ini
At this point, I strongly recommend closing ALL your terminal tabs and windows. This will mean opening a new terminal to continue with the next step. This is strongly recommended because some really strange path issues can arise with existing terminals [trust me, I have seen it!].
We have installed but not linked these PHP versions. To switch to PHP 7.3
for example we can type:
brew unlink php && brew link --overwrite --force [email protected]
Quick test that we're in the correct version:
php -v
PHP 7.3.32 [cli] [built: Oct 29 2021 00:43:12] [ NTS ]
Copyright [c] 1997-2018 The PHP Group
Zend Engine v3.3.32, Copyright [c] 1998-2018 Zend Technologies
with Zend OPcache v7.3.32, Copyright [c] 1999-2018, by Zend Technologies
and to switch to to 7.4
:
brew unlink php && brew link --overwrite --force [email protected]
And check that it's changed correctly:
php -v
PHP 7.4.25 [cli] [built: Oct 21 2021 00:29:22] [ NTS ]
Copyright [c] The PHP Group
Zend Engine v3.4.0, Copyright [c] Zend Technologies
with Zend OPcache v7.4.25, Copyright [c], by Zend Technologies
Apache PHP Setup - Part 1
You have successfully installed your PHP versions, but we need to tell Apache to use them. You will again need to edit the /opt/homebrew/etc/httpd/httpd.conf
file
scroll to the bottom of the LoadModule
entries.
If you have been following this guide correctly, the last entry should be your mod_rewrite
module:
LoadModule rewrite_module lib/httpd/modules/mod_rewrite.so
Below this add the following libphp
modules:
#LoadModule php7_module /opt/homebrew/opt/[email protected]/lib/httpd/modules/libphp7.so
#LoadModule php7_module /opt/homebrew/opt/[email protected]/lib/httpd/modules/libphp7.so
#LoadModule php7_module /opt/homebrew/opt/[email protected]/lib/httpd/modules/libphp7.so
#LoadModule php7_module /opt/homebrew/opt/[email protected]/lib/httpd/modules/libphp7.so
LoadModule php7_module /opt/homebrew/opt/[email protected]/lib/httpd/modules/libphp7.so
#LoadModule php_module /opt/homebrew/opt/[email protected]/lib/httpd/modules/libphp.so
We can only have one module processing PHP at a time, so for now, so we have left our [email protected]
entry uncommented while all the others are commented out. This will tell Apache to use PHP 7.4 to handle PHP requests. [We will add the ability to switch PHP versions
later].
Also you must set the Directory Indexes for PHP explicitly, so search for this block:
DirectoryIndex index.html
and replace it with this:
DirectoryIndex index.php index.html
SetHandler application/x-httpd-php
Save the file and stop Apache then start again, now that we have installed PHP:
brew services stop httpd
brew services start httpd
Validating PHP Installation
The best way to test if PHP is installed and running as expected is to make use of phpinfo[]. This is not something you want to leave on a production machine, but it's invaluable in a development environment.
Simply create a file called info.php
in your Sites/
folder you created earlier with this one-liner.
echo "