Apache Installation

aa The latest macOS 11.0 Big Sur 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

Copy

Now we need to install the new version provided by Brew:

brew install httpd

Copy

Without options, <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">httpd won't need to be built from source, so it installs pretty quickly. Upon completion you should see a message like:

🍺  /usr/local/Cellar/httpd/2.4.46: 1,658 files, 27.9MB

Copy

Now we just need to configure things so that our new Apache server is auto-started

brew services start httpd

Copy

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 <code style="background-color: rgb(241, 241, 254); color: rgb(17, 149, 220);">http://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

Copy

You should see a few httpd processes if Apache is up and running.

Try to restart Apache with:

brew services restart httpd

Copy

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 /usr/local/var/log/httpd/error_log

Copy

Apache is controlled via the <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">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 <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">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.

Go to the Visual Studio Code site and click Download for Mac

Once downloaded, drag the application to your preffered Applications location. Next, you want to install the command line tools, so follow the official step-by-step instructions so that you can use the <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">code command from the Terminal.

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 <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">8080 to <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">80, so we will need to edit Apache's configuration file <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">/usr/local/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 style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">code Terminal command. However, if you want to use the default TextEditor application to perform edits, you can use the <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">open -e command followed by the path to the file.

code /usr/local/etc/httpd/httpd.conf

Copy

Find the line that says

Listen 8080

Copy

and change it to <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">80:

Listen 80

Copy

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 <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">/usr/local/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 <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">DocumentRoot, and you should see the following line:

DocumentRoot "/usr/local/var/www"

Copy

Change this to point to your user directory where <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">your_user is the name of your user account:

DocumentRoot /Users/your_user/Sites

Copy

You also need to change the <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);"><Directory> tag reference right below the DocumentRoot line. This should also be changed to point to your new document root also:

<Directory "/Users/your_user/Sites">

In that same <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);"><Directory> block you will find an <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">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

Copy

Also we should now enable mod_rewrite which is commented out by default. Search for <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">mod_rewrite.so and uncomment the line by removing the leading <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);"># by pushing <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">⌘ + <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">/ 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

Copy

User & Group

Now we have the Apache configuration pointing to a <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">Sites folder in our home directory. One problem still exists, however. By default, apache runs as the user <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">daemon and group <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">daemon. This will cause permission problems when trying to access files in our home directory. About a third of the way down the <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">httpd.conf file there are two settings to set the <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">User and <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">Group Apache will run under. Change these to match your user account (replace <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">your_user with your real username), with a group of <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">staff:

User your_user
Group staff

Copy

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

Copy

and replace it with:

ServerName localhost

Copy

Sites Folder

Now, you need to create a <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">Sites folder in the root of your home directory. You can do this in your terminal, or in Finder. In this new <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">Sites folder create a simple <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">index.html and put some dummy content in it like: <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);"><h1>My User Web Root</h1>.

mkdir ~/Sites
echo "<h1>My User Web Root</h1>" > ~/Sites/index.html

Copy

Restart apache to ensure your configuration changes have taken effect:

brew services stop httpd
brew services start httpd

Pointing your browser to <code style="color: rgb(17, 149, 220); background-color: rgb(241, 241, 254);">http://localhost should display your new message. If you have that working, we can move on!

Troubleshooting Non-Sudo httpd Services Start

This year, with macOS Big Sur, I've switched from using <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">sudo to launch <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">httpd with root (even though it ran as the user/group defined in <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">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 <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">brew services start httpd.

First, try to start apache directly with:

/usr/local/bin/httpd -k start

Copy

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 /usr/local/var/log/httpd/*

Copy

Then try starting again.

If you have see a message saying something like <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">Address already in use: AH00072: make_sock: could not bind to address, try changing the <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">Listen config in <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">httpd.conf to:

Listen 0.0.0.0:80

Copy

PHP Installation

Up until the end of March 2018, all PHP related brews were handled by <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">Homebrew/php tab, but that has been deprecated, so now we use what's available in the <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">Homebrew/core package. This should be a better maintained, but is a much less complete, set of packages.

PHP 5.6, 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 <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">icu4c and <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">openssl.

Remember only PHP 7.2 through 7.4 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 PHP 8.0 builds) pre-built.

PHP 8.0 has just been released and you are able to install it, but it might take some time for compatible PHP modules are fully available.

brew tap shivammathur/php

Copy

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/php@5.6
brew install shivammathur/php/php@7.0
brew install shivammathur/php/php@7.1
brew install shivammathur/php/php@7.2
brew install shivammathur/php/php@7.3
brew install shivammathur/php/php@7.4
brew install shivammathur/php/php@8.0

Copy

Also, you may have the need to tweak configuration settings of PHP to your needs. A common thing to change is the memory setting, or the <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">date.timezone configuration. The <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">php.ini files for each version of PHP are located in the following directories:

/usr/local/etc/php/5.6/php.ini
/usr/local/etc/php/7.0/php.ini
/usr/local/etc/php/7.1/php.ini
/usr/local/etc/php/7.2/php.ini
/usr/local/etc/php/7.3/php.ini
/usr/local/etc/php/7.4/php.ini
/usr/local/etc/php/8.0/php.ini

We have installed but not linked these PHP versions. To switch to PHP <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">5.6 for example we can type:

brew unlink php && brew link --overwrite --force php@5.6

Copy

Quick test that we're in the correct version:

php -v

Copy

PHP 5.6.40 (cli) (built: Jul  2 2020 04:41:54) 
Copyright (c) 1997-2016 The PHP Group
Zend Engine v2.6.0, Copyright (c) 1998-2016 Zend Technologies
    with Zend OPcache v7.0.6-dev, Copyright (c) 1999-2016, by Zend Technologies

Copy

and to switch to to <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">7.4:

brew unlink php && brew link --overwrite --force php@7.4

Copy

And check that it's changed correctly:

php -v

Copy

PHP 7.4.12 (cli) (built: Oct 30 2020 00:56:27) ( NTS )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies
    with Zend OPcache v7.4.12, Copyright (c), by Zend Technologies

Copy

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 <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">/usr/local/etc/httpd/httpd.conf file scroll to the bottom of the <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">LoadModule entries.

If you have been following this guide correctly, the last entry should be your <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">mod_rewrite module:

LoadModule rewrite_module lib/httpd/modules/mod_rewrite.so

Copy

Below this add the following <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">libphp modules:

LoadModule php5_module /usr/local/opt/[email protected]/lib/httpd/modules/libphp5.so
#LoadModule php7_module /usr/local/opt/[email protected]/lib/httpd/modules/libphp7.so
#LoadModule php7_module /usr/local/opt/[email protected]/lib/httpd/modules/libphp7.so
#LoadModule php7_module /usr/local/opt/[email protected]/lib/httpd/modules/libphp7.so
#LoadModule php7_module /usr/local/opt/[email protected]/lib/httpd/modules/libphp7.so
#LoadModule php7_module /usr/local/opt/[email protected]/lib/httpd/modules/libphp7.so
#LoadModule php_module /usr/local/opt/[email protected]/lib/httpd/modules/libphp.so

Copy

We can only have one module processing PHP at a time, so for now, so we have left our <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">[email protected] entry uncommented while all the others are commented out. This will tell Apache to use PHP 5.6 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:

<IfModule dir_module>
    DirectoryIndex index.html
</IfModule>

Copy

and replace it with this:

<IfModule dir_module>
    DirectoryIndex index.php index.html
</IfModule>

<FilesMatch .php$>
    SetHandler application/x-httpd-php
</FilesMatch>

Copy

Save the file and stop Apache then start again, now that we have installed PHP:

brew services stop httpd
brew services start httpd

Copy

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 <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">info.php in your <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">Sites/ folder you created earlier with this one-liner.

echo "<?php phpinfo();" > ~/Sites/info.php

Copy

Point your browser to <code style="background-color: rgb(241, 241, 254); color: rgb(17, 149, 220);">http://localhost/info.php and you should see a shiny PHP information page:

If you see a similar phpinfo result, congratulations! You now have Apache and PHP running successfully. You can test the other PHP versions by commenting the <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">LoadModule ... [email protected] ... entry and uncommenting one of the other ones. Then simply restart apache and reload the same page.

PHP Switcher Script

We hard-coded Apache to use PHP 5.6, but we really want to be able to switch between versions. Luckily, some industrious individuals have already done the hard work for us and written a very handy little PHP switcher script.We will install the <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">sphp script into brew's standard <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">/usr/local/bin:

curl -L https://gist.githubusercontent.com/rhukster/f4c04f1bf59e0b74e335ee5d186a98e2/raw/0c36a5067fbd63e6a36700a6aaa119df0836bdfc/sphp.sh > /usr/local/bin/sphp
chmod +x /usr/local/bin/sphp

Copy

Check Your Path

Homebrew should have added its preferred <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">/usr/local/bin and <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">/usr/local/sbin to your path as part of its installation process. Quickly test this by typing:

echo $PATH
/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

Copy

If you don't see this, first try closing your terminal and restarting it. If that doesn't work, check that you have <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">/usr/local/binbefore <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">/usr/bin and <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">/usr/local/sbin before <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">/usr/sbin in the path definition of your <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">~/.zshrc file. You can do it temporarily in the shell by typing:

export PATH=/usr/local/bin:/usr/local/sbin:$PATH

Copy

Testing the PHP Switching

After you have completed these steps, you should be able to switch your PHP version by using the command <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">sphp followed by a two digit value for the PHP version:

sphp 7.1

Copy

You will probably have to enter your administrator password, and it should give you some feedback:

Switching to php@7.4

Copy

Switching to php@7.4 Switching your shell Unlinking /usr/local/Cellar/php@5.6/5.6.40... 0 symlinks removed Unlinking /usr/local/Cellar/php@7.1/7.1.33... 0 symlinks removed Unlinking /usr/local/Cellar/php@7.2/7.2.34... 0 symlinks removed Unlinking /usr/local/Cellar/php/7.4.12... 24 symlinks removed Linking /usr/local/Cellar/php/7.4.12... 24 symlinks created Switching your apache conf Restarting apache PHP 7.4.12 (cli) (built: Oct 30 2020 00:56:27) ( NTS ) Copyright (c) The PHP Group Zend Engine v3.4.0, Copyright (c) Zend Technologies with Zend OPcache v7.4.12, Copyright (c), by Zend Technologies All done!

Test to see if your Apache is now running PHP 7.4 by again pointing your browser to <code style="background-color: rgb(241, 241, 254); color: rgb(17, 149, 220);">http://localhost/info.php. With a little luck, you should see something like this:

Troubleshooting PHP Switching

If you have upgraded from a previous version of this guide and have installed PHP8, you may see message like: <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">Unknown version of PHP. PHP Switcher can only handle arguments of: 5.6,7.0,7.1,7.2,7.3,7.4, then you need to reinstall the <code style="background-color: rgb(241, 241, 254); color: rgb(118, 118, 244);">sphp script which has been updated.

If you get a message about conflicting PHP versions, then you probably have a conflict of taps. You will need to uninstall your previous PHP versions, then remove the old tap, then add the new tap, and then reinstall PHP versions using the syntax above. For example:

brew untap exolnet/deprecated
brew tap shivammathur/php
brew install shivammathur/php/php@8.0