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 https://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, but when complete, a quick way to ensure you have installed brew correctly, simply type:
brew --version
Homebrew 2.1.13
Homebrew/homebrew-core (git revision 99f8; last commit 2019-10-08)
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.
When installing fresh on Catalina, I ran into a few libraries that were missing when completing all the steps below. To make things easier, please simply run these now:
brew install openldap libiconv
The latest macOS 10.15 Catalina 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 stopimage 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:
🍺 /usr/local/Cellar/httpd/2.4.41_1: 1,652 files, 27.7MB
Now we just need to configure things so that our new Apache server is auto-started
$ sudo 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 http://localhost:8080, you should see a simple header that says "It works!".
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:
sudo apachectl -k restart
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
Apache is controlled via the apachectl command so some useful commands to use are:
sudo apachectl start sudo apachectl stop sudo apachectl -k restart
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.
/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 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.
atom /usr/local/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 /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 DocumentRoot, and you should see the following line:
DocumentRoot "/usr/local/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 <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 <Directory> 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 #:
LoadModule rewrite_module lib/httpd/modules/mod_rewrite.so
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
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
in my case iam use
ServerName jlcnate.local
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 Sitesfolder create a simple index.html and put some dummy content in it like: <h1>My User Web Root</h1>.
mkdir ~/Sites
echo "<h1>My User Web Root</h1>" > ~/Sites/index.html
Restart apache to ensure your configuration changes have taken effect:
sudo apachectl -k restart
Pointing your browser to http://localhost should display your new message. If you have that working, we can move on!
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 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.
Remember only PHP 7.2 through 7.4 are officially supported by Brew so if you want to install PHP 5.6, PHP 7.0, or PHP 7.1 you will need to add this tap:
brew tap exolnet/homebrew-deprecated
We will proceed by installing various verions 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 php@5.6
$ brew install php@7.0
$ brew install php@7.1
$ brew install php@7.2
$ brew install php@7.3
$ brew install php@7.4
The first one will take a little bit of time as it has to install a bunch of brew dependencies. Subsequent PHP versions will install faster.
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 date.timezone configuration. The 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
Let's switch back to the first PHP version now:
$ brew unlink php@7.4 && brew link --force --overwrite php@5.6
Quick test that we're in the correct version:
php -v PHP 5.6.40 (cli) (built: Apr 23 2019 11:14:34) 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
You have successfully installed your PHP versions, but we need to tell Apache to use them. You will again need to edit the /usr/local/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 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
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 teh 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>
and replace it with this:
<IfModule dir_module>DirectoryIndex index.php index.html
</IfModule>
<FilesMatch .php$>SetHandler application/x-httpd-php
</FilesMatch>
Save the file and stop Apache then start again, now that we have installed PHP:
sudo apachectl -k stop sudo apachectl start
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 "<?php phpinfo();" > ~/Sites/info.php
Point your browser to 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 LoadModule ... [email protected] ... entry and uncommenting one of the other ones. Then simply restart apache and reload the same page.
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 sphp script into brew's standard /usr/local/bin:
$ curl -L https://gist.githubusercontent.com/rhukster/f4c04f1bf59e0b74e335ee5d186a98e2/raw > /usr/local/bin/sphp
$ chmod +x /usr/local/bin/sphp
Homebrew should have added its preferred /usr/local/bin and /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:/Library/Apple/usr/bin:/Library/Apple/bin
If you don't see this, you might need to add these manually to your path. Depending on your shell your using, you may need to add this line to ~/.profile, ~/.bash_profile, or ~/.zshrc. We will assume you are using the default bash shell, so add this line to a your .profile(create it if it doesn't exist) file at the root of your user directory:
export PATH=/usr/local/bin:/usr/local/sbin:$PATH
After you have completed these steps, you should be able to switch your PHP version by using the command sphp followed by a two digit value for the PHP version:
sphp 7.1
You will probably have to enter your administrator password, and it should give you some feedback:
Switching to php@7.1
Switching your shell
Unlinking /usr/local/Cellar/php@5.6/5.6.40... 319 symlinks removed
Unlinking /usr/local/Cellar/php@7.1/7.1.33... 0 symlinks removed
Unlinking /usr/local/Cellar/php@7.2/7.2.25... 0 symlinks removed
Unlinking /usr/local/Cellar/php@7.3/7.3.12... 0 symlinks removed
Unlinking /usr/local/Cellar/php/7.4.0... 0 symlinks removed
Linking /usr/local/Cellar/php@7.1/7.1.33... 25 symlinks created
If you need to have this software first in your PATH instead consider running:
echo 'export PATH="/usr/local/opt/[email protected]/bin:$PATH"' >> ~/.zshrc
echo 'export PATH="/usr/local/opt/[email protected]/sbin:$PATH"' >> ~/.zshrc
You will need sudo power from now on
Switching your apache conf
Restarting apache
PHP 7.1.33 (cli) (built: Nov 28 2019 14:00:51) ( NTS )
Copyright (c) 1997-2018 The PHP Group
Zend Engine v3.1.0, Copyright (c) 1998-2018 Zend Technologies
with Zend OPcache v7.1.33, Copyright (c) 1999-2018, by Zend Technologies
All done!
Test to see if your Apache is now running PHP 7.1 by again pointing your browser to http://localhost/info.php. With a little luck, you should see something like this:
If you have already installed this setup prior to December 2019, where PHP 7.3 was the latest, you can easily update your setup to support the new PHP 7.4 version with a few steps:
Update to latest PHP 7.4 with brew update && brew upgrade
This will upgrade the default php package from 7.3 to 7.4. You then need to re-install PHP 7.3 with: brew install [email protected]
Update the PHP switcher script (sphp) with the latest version that adds support for PHP 7.4 by re-running the commands:
$ curl -L https://gist.githubusercontent.com/rhukster/f4c04f1bf59e0b74e335ee5d186a98e2/raw > /usr/local/bin/sphp
$ chmod +x /usr/local/bin/sphp
Add a new entry in your httpd.conf for the PHP 7.4's libphp below the 7.3 entry:
... 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
Next you have to create a symbolic link for /usr/local/opt/[email protected] as brew installs PHP 7.4 as /usr/local/opt/php:
ln -s /usr/local/opt/php /usr/local/opt/php@74
That's it, just sphp 7.4 to Switch to PHP 7.4 and you should be good to go!
Updating PHP and other Brew Packages
Brew makes it super easy to update PHP and the other packages you install. The first step is to update Brew so that it gets a list of available updates:
brew update
This will spit out a list of available updates, and any deleted formulas. To upgrade the packages simply type:
brew upgrade
Activating Specific/Latest PHP Versions
Due to the way our PHP linking is set up, only one version of PHP is linked at a time, only the current active version of PHP will be updated to the latest version. You can see the current active version by typing:
php -v
And you can see the specific versions of a PHP package by typing:
$ brew info php@7.1
exolnet/deprecated/php@7.1: stable 7.1.33 (bottled) [keg-only]
General-purpose scripting language
https://www.php.net/
/usr/local/Cellar/php@7.1/7.1.33 (509 files, 62.8MB) *
Poured from bottle on 2019-12-02 at 09:53:53
From: https://github.com/exolnet/homebrew-deprecated/blob/master/Formula/php@7.1.rb
==> Dependencies
Build: httpd ✔, pkg-config ✔
Required: apr ✔, apr-util ✔, aspell ✔, autoconf ✔, curl-openssl ✔, freetds ✔, freetype ✔, gettext ✔, glib ✔, gmp ✔, icu4c ✔, jpeg ✔, libpng ✔, libpq ✔, libtool ✔, libzip ✔, mcrypt ✔, openldap ✔, openssl@1.1 ✔, sqlite ✔, tidy-html5 ✔, unixodbc ✔, webp ✔
...