- As a tl;dr, we’ll be setting up Homebrew MySQL and PHP and using OSX’s built in Apache. In this tutorial I’m using the subl command which will open a file for editing in Sublime Text. If you don’t use Sublime Text, replace subl with nano or vi or any other app you use to edit text/config files.
- The main content of this paper is translated from MacOS 10.12 Sierra Apache setup: multiple PHP versions, and it has joined its own practice. It’s really a troublesome thing to build development environment every time, but with the passage of time and the difference of system environment, the experience of online tutorial installation is often.
And then restart Apache using the following command. $ sudo apachectl restart PHP. MacOS Mojave comes with PHP 7.1.x pre-installed. To check the version of PHP in the Terminal type the following command. $ php -v Alright, type the following command in the terminal to go to apache2 directory. $ cd /etc/apache2/ Open the httpd.conf file.
First part in a multi-part blog series for Mac developers
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.
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:
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:
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 <Directory> 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 <Directory> 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: <h1>My User Web Root</h1>.
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!
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. 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 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.
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 upgradeThis will upgrade the default
phppackage from 7.3 to 7.4. You then need to re-install PHP 7.3 with:brew install php@7.3Update the PHP switcher script (
sphp) with the latest version that adds support for PHP 7.4 by re-running the commands:Add a new entry in your
httpd.conffor the PHP 7.4'slibphpbelow the 7.3 entry:Next you have to create a symbolic link for
/usr/local/opt/php@7.4as brew installs PHP 7.4 as/usr/local/opt/php:
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.
Please enable JavaScript to view the comments powered by Disqus.Get your Local Web Development Environment Up & Running on macOS Catalina 10.15
With Apples’ new macOS Catalina 10.15 available for download, here is how to get the AMP stack up and running on the new macOS. This tutorialwill go through the process of getting Apache, MySQL, PHP (or otherwise known as the ‘AMP’ stack)and phpMyAdmin running on the new mac OS Catalina.
This tutorial sets up the AMP stack in more of a traditional way using the loaded Apache and PHP and downloading MySQL and phpMyAdmin.
Setting Stuff Up
Apache/WebSharing
Web serving is built into Catalina with Apache app, it is installed ready to be fired up.
This needs to be done in the Terminal which is found in the OS filing system at /Applications/Utilities/Terminal
For those not familiar with the Terminal, it really isn’t as intimidating as you may think, once launched you are faced with a command prompt waiting for your commands – just type/paste in a command and hit enter, some commands give you no response – it just means the command is done, other commands give you feedback.
Using the prefix of sudo is required for commands that have their applications protected in specific folders – when using sudo you will need to confirm with your admin password or iCloud password if set up that way…. let’s get to it …
to start Apache web sharing
to stop it
to restart it
To find the Apache version
The Apache version that comes in macOS Catalina is Apache/2.4.41
After starting Apache – test to see if the webserver is working in the browser – http://localhost – you should see the “It Works!” text.
If you don’t get the localhost test, you can try troubleshooting Apache to see if there is anything wrong in its config file by running
This will give you an indication of what might be wrong.
Document Root
Document root is the location where the files are shared from the file system and is similar to the traditional names of ‘public_html‘ and ‘htdocs‘, macOS has historically had 2 web roots one at a system level and one at a user level – you can set both up or just run with one, the user level one allows multiple accounts to have their own web root whilst the system one is global for all users. It seems there is less effort from Apple in continuing with the user level one but it still can be set up with a couple of extra tweaks in configuration files. It is easier to use the user level one as you don’t have to keep on authenticating as an admin user.
System Level Web Root
– the default system document root is still found at –
http://localhost/
The files are shared in the filing system at –
User Level Root
The other web root directory which is missing by default is the ‘~/Sites’ folder in the User account. This takes a bit longer to set up but some users are very accustomed to using it.
You need to make a “Sites” folder at the root level of your account and then it will work. Once you make the Sites folder you will notice that it has a unique icon which is a throwback from a few versions older. Make that folder before you set up the user configuration file described next.
You have to make a few additional tweaks to get the ~/Sites folder back up and running.
Add a “username.conf” filed under:
If you don’t already have one (very likely), then create one named by the short username of the account with the suffix .conf, its location and permissions/ownership is best tackled by using the Terminal, the text editor ‘nano‘ would be the best tool to deal with this.
If you would rather edit config files in a text editor as an app I would suggest text editor like the free BBEdit which allows you to open hidden system files.
Launch Terminal, (Applications/Utilities), and follow the commands below, first one gets you to the right spot, 2nd one opens the text editor on the command line (swap ‘username‘ with your account’s shortname, if you don’t know your account shortname type ‘whoami‘ the Terminal prompt):
Then add the content below swapping in your ‘username’ in the code below, there is a slightly different user directive for Catalina, make sure ‘Require host localhost’ is used:
Permissions on the file should be:
If not, you need to change it…
Open the main httpd.conf and allow some modules:
And make sure these modules are uncommented (the first 2 should already be on a clean install):
While you have this file open also to get php running, uncomment the below … (Mentioned also in the PHP part of the article).
And also uncomment this configuration file also in httpd.conf – which allows user home directories.
Save all your changes (Control + O in nano)
Then open another Apache config file and uncomment another file:
And uncomment:
Save all your changes (Control + O in nano)
Restart Apache for the new file to be read:
Then this user level document root will be viewable at:
http://localhost/~username/
You should only see a directory tree like structure if the folder is empty.
Override .htaccess and allow URL Rewrites
If you are going to use the web serving document root at /Library/WebServer/Documents it is a good idea to allow any .htaccess files used to override the default settings – this can be accomplished by editing the httpd.conf file at line 217 and setting the AllowOverride to All and then restart Apache. This is already taken care of at the Sites level webroot by following the previous step.
Also while here allow URL rewrites so your permalinks look clean, not ugly.
Uncomment in httpd.conf – should be uncommented on a clean install.
PHP
PHP 7.3.8 is loaded in this version of macOS Catalina and needs to be turned on by uncommenting a line in the httpd.conf file.
Use “control” + “w” to search within nano and search for ‘php’ this will land you on the right line then uncomment the line (remove the #):
Write out and Save using the nano shortcut keys at the bottom ‘control o’ and ‘control x’
Reload Apache to kick in
To see and test PHP, create a file name it “phpinfo.php” and file it in your document root with the contents below, then view it in a browser.
MySQL
MySQL doesn’t come pre-loaded with macOS Catalina and needs to be dowloaded from the MySQL site.
The latest version of MySQL 8.0.17 does work with the public release of macOS.
Use the macOS 10.14 (x86, 64-bit), DMG Archive version (works on macOS Catalina).
Apache Php Mysql For Mac
If you are upgrading from a previous macOS and have an older MySQL version you do not have to update it.
Also if you have a clean install and want the earlier MySQL version 5.7, you can still get this from the MySQL site – from the ‘Looking for previous GA versions’ link. (MySQL 8 is relatively new and not in many production set ups)
One thing with MySQL upgrades, always take a data dump of your database in case things go south and before you upgrade to macOS Catalina make sure your MySQL Server is not running.
When downloading you don’t have to sign up, look for » No thanks, just take me to the downloads! – go straight to the download mirrors and download the software from a mirror which is closest to you.
Once downloaded open the .dmg and run the installer.
During the MySQL process you are prompted to choose between strong and legacy password encryptions, since version 8 is entirely new, some software like phpMyAdmin can’t connect with the newer encryptions – so if you are going to use a GUI wrapper like phpMyadmin I suggest you stick to legacy.
Then add a password for the MySQL root user.
Add Mysql to your path
After installation, in order to use MySQL commands without typing the full path to the commands you need to add the mysql directory to your shell path, (optional step) this is done in your Zsh shell profile “.zsh” file in your home directory (previous shells were bash), if you don’t have that file just create it using vi or nano:
The first command brings you to your home directory and opens the .zsh file or creates a new one if it doesn’t exist, then add in the line above which adds the MySQL binary path to commands that you can run. Exit the file with type “control + x” and when prompted to save the change by typing “y”. The last thing to do here is to reload the shell for the above to work straight away.
Change the MySQL root password
(This section is left in for reference – in previous macOS MySQL packages the password set during the installation process would fail – hence the info below. This newer version, however, seems to work).
Note that this is not the same as the root or admin password of macOS – this is a unique password for the MySQL root user.
Stop MySQL
Start it in safe mode:
This will be an ongoing command until the process is finished so open another shell/terminal window, and log in without a password as root:
Change the lowercase ‘MyNewPass’ to what you want – and keep the single quotes.
Start MySQL
Starting MySQL
You can then start the MySQL server from the System Preferences or via the command line.
The new MySQL system preference also has the uninstall feature – useful if you’ve installed it with a security encryption that’s not working for you and want to try the other one. You can also see the paths to the config and data sources of MySQL in the configuration tab.
Or to Command line start MySQL.
To find the MySQL version from the terminal, type at the prompt:
This also puts you into a shell interactive dialogue with MySQL, type q to exit.
Fix the 2002 MySQL Socket error
Apache Server Mac
Fix the looming 2002 socket error – which is linking where MySQL places the socket and where macOS thinks it should be, MySQL puts it in /tmp and macOS looks for it in /var/mysql the socket is a type of file that allows MySQL client/server communication.
phpMyAdmin
First fix the 2002 socket error if you haven’t done so from the MySQL section-
Apache Php Macos
Download phpMyAdmin, the zip English package will suit a lot of users, then unzip it and move the folder with its contents into the document root level renaming folder to ‘phpmyadmin’.
Make the config folder
Change the permissions
Run the set up in the browser
http://localhost/~username/phpmyadmin/setup/ orhttp://localhost/phpmyadmin/setup/
You need to create a new localhost mysql server connection, click new server.
Switch to the Authentication tab and set the local MySQL root user and the password.
Add in the username “root” (maybe already populated, add in the password that you set up earlier for the MySQL root user set up, click on save and you are returned to the previous screen.
(This is not the macOS Admin or root password – it is the MySQL root user)
Apache Mysql Php For Mac
Now going to http://localhost/~username/phpmyadmin/ will now allow you to interact with your MySQL databases.
Permissions
To run a website with no permission issues it is best to set the web root and its contents to be writeable by all since it’s a local development it shouldn’t be a security issue.
Let’s say that you have a site in the User Sites folder at the following location ~/Sites/testsite you would set it to be writeable like so:
If you are concerned about security then instead of making it world writeable you can set the owner to be Apache _www but when working on files you would have to authenticate more as admin you are “not” the owner, you would do this like so:
This will set the contents recursively to be owned by the Apache user.
If you had the website stored at the System level Document root at say /Library/WebServer/Documents/testsite then it would have to be the latter:
Another more straightforward way to do this if you have a one user workstation is to change the Apache web user from _www to your account.
That’s it! You now have the native AMP stack running on top of macOS Catalina.
If you are a WordPress user and want a smooth lean local development environment – also worth checking out is Laravel Valet which runs on top of macOS – check out my Valet WordPress Guide on macOS.