Part 1: macOS 10.15 Catalina 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.
[Updated 12/02/2019] Updated to reflect the latest release of PHP 7.4 and the removal of PHP 7.1 from Official tap
[Updated 10/08/2019] Updated to reflect the release of macOS 10.15 Catalina
[Updated 01/10/2019] Updated to add back PHP 5.6 and PHP 7.0 from and external deprecated keg
[Updated 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:
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:
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:
You should probably also run the following command to ensure everything is configured correctly:
It will instruct you if you need to correct anything.
Catalina Required Libraries
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:
Apache Installation
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:
Now we need to install the new version provided by Brew:
Without options, httpd won't need to be built from source, so it
installs pretty quickly. Upon completion you should see a message like:
Now we just need to configure things so that our new Apache server is auto-started
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!".
Troubleshooting Tips
If you get a message that the browser can't connect to the server, first check to ensure the server is up.
You should see a few httpd processes if Apache is up and running.
Try to restart Apache with:
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:
Apache is controlled via the
apachectl command so some useful commands to use are:
The -k will force a restart immediately rather than asking politely to restart when apache is good and ready
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 Catalina,
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 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
8080 to
80, so we will need to edit Apache's configuration file.
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.
Find the line that says
and change it to
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:
Change this to point to your user directory where
your_user is the name of your user account:
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:
We removed the optional quotes around the directory
paths as TextEdit will probably try to convert those to smart-quotes and
that will result in a Syntax error when you try to restart Apache. Even
if you edit around the quotes and leave them where they are, saving the
document may result in their conversion and cause an error.
In that same
block you will find an
AllowOverride setting, this should be changed as follows:
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
#:
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:
Servername
Apache likes to have a server name in the configuration, but this is disabled by default, so search for:
and replace it with:
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
.
Restart apache to ensure your configuration changes have taken effect:
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
http://localhost should display your new message. If you have that working, we can move on!
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 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:
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.
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.
You no longer have to unlink each version between installing PHP versions as they are not linked by default
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:
Let's switch back to the first PHP version now:
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!).
Quick test that we're in the correct version:
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
/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:
Below this add the following
libphp modules:
We can only have one module processing PHP at a time, so for now, so we have left our
php@5.6 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:
and replace it with this:
Save the file and
stop Apache then start again, now that we have installed PHP:
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.
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 ... php@5.6 ... 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
sphp script into brew's standard
/usr/local/bin:
Check Your Path
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:
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:
Testing the PHP Switching
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:
You will probably have to enter your administrator password, and it should give you some feedback:
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:
Upgrading your system to PHP 7.4
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 php@7.3
-
Update the PHP switcher script (
sphp) with the latest version that adds support for PHP 7.4 by re-running the commands:
-
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:
This will spit out a list of available updates, and any deleted formulas. To upgrade the packages simply type:
You will need to switch to each of your installed PHP versions and run update again to get updates for each PHP version and ensure you are running the version of PHP you intend.
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:
And you can see the specific versions of a PHP package by typing:
OK, that wraps up Part 1 of this 3 part series You now have a fully
functional Apache 2.4 installation with a quick-and-easy way to toggle
between PHP 5.6, 7.0, 7.1, 7.2, 7.3 and 7.4.
Check out Part 2 to find out how to setup your environment with
MySQL,
Virtual Hosts,
APC caching,
YAML, and
Xdebug. Also
take a gander at Part 3 to find out how to setup
SSL for your Apache Virtual Hosts.
