This tutorial will go through the process of getting Apache, MySQL, PHP (or otherwise known as the 'AMP' stack) and phpMyAdmin running on the new mac OS Big Sur. This guide will also work on macOS Catalina and Mojave. This tutorial sets up the AMP stack in more of a traditional way using the loaded Apache and PHP and downloading MySQL. In Part 1 of this 3-part series, we covered configuring Apache on macOS to work better with your local user account, as well as the installation process for installing multiple versions of PHP. In this Part 2, we will cover installing MySQL, Virtual Hosts, APC caching, YAML, and Xdebug.
Second part in a multi-part blog series for Mac developers
Part 2: macOS 11.0 Big Sur Web Development Environment
In Part 1 of this 3-part series, we covered configuring Apache on macOS to work better with your local user account, as well as the installation process for installing multiple versions of PHP.
Install Apache Php Mysql Mac Catalina Free
In this Part 2, we will cover installing MySQL, Virtual Hosts, APC caching, YAML, and Xdebug. After finishing this tutorial, be sure to check out how to enable SSL in Part 3 of the series.
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.
This guide is intended for experienced web developers. If you are a beginner developer, you will be better served using MAMP or MAMP Pro.
Although not required for development of Grav, there are times you definitely need an installation of MySQL. In the original guide, we used the Oracle MySQL installation package. However, we now have switched to MariaDB which is a drop-in replacement for MySQL and is easily installed and updated with Brew. Detailed information on the HomeBrew installation process can be found on the mariadb.org site but the essentials are as follows:
Install MariaDB with Brew:
After a successful installation, you can start the server ane ensure it autostarts in the future with:
You should get some positive feedback on that action:
You must change MySQL server password and secure your installation. The simplest way to do this is to use the provided script:
Just answer the questions and fill them in as is appropriate for your environment. You can just press return when prompted for the current root password.
Download TablePlus and install it. (it's awesome and there's a free version!). You should be create a new MySQL connection, give it a Name, a color, and check Use socket option after you enter a User of root and your newly created password.
If you need to stop the server, you can use the simple command:
A very handy development option is to have multiple virtual hosts set up for you various projects. This means that you can set up names such as grav.mydomain.com which point to your Grav setup, or project-x.mydomain.com for a project-specific URL.
Apache generally performs name-based matching, so you don't need to configure multiple IP addresses. Detailed information can be found on the apache.org site.
Apache already comes preconfigured to support this behavior but it is not enabled. First you will need to uncomment the following lines in your /usr/local/etc/httpd/httpd.conf file:
and:
Then you can edit this referenced file and configure it to your needs:
This file has some instructions already but the important thing to remember is that these rules are matched in order. When you set up virtual hosts, you will lose your older document root, so you will need to add back support for that first as a virtual host.
Don't forget to change your_user for your actual username on your Mac. For example: DocumentRoot '/Users/bernard/Sites'
As you set up your .test virtual hosts, you may receive a warning such as Warning: DocumentRoot [/Users/your_user/Sites/grav-admin] does not exist when restarting Apache. This just lets you know that the source directory listed for your virtual hosts is not present on the drive. It's an issue that can be resolved by editing this file with the corrected DocumentRoot.
We used to recommend using .dev domain name, but since Chrome 63 forces all .dev domains to use SSL, this guide has been updated to use .test
In the example virtualhost we setup above, we defined a ServerName of grav-admin.test. This by default will not resolve to your local machine, but it's often very useful to be able to setup various virtual hosts for development purposes. You can do this by manually adding entries to /etc/hosts ever time, or you can install and configure Dnsmasq to automatically handle wildcard *.test names and forward all of them to localhost (127.0.0.1).
First we install it with brew:
Then we setup *.test hosts:
Start it and ensure it auto-starts on reboot in the future:
And lastly, add it to the resolvers:
Now you can test it out by pinging some bogus .test name:
Voila! we have successfully setup wildcard forwarding of all *.test DNS names to localhost.
Caching in PHP is a big part of the performance equation. There are two types of caching typically available, and both have a big impact on speed and performance.
The first type of cache is called an opcode cache, and this is what takes your PHP script and compiles it for faster execution. This alone can typically result in a 3X speed increase!.
The second type of cache is a user cache, and this is a entry that PECL adds to the top of your php.ini. So edit this file and remove the top line:
Once that line is removed, we can add a new file with a proper entry to the recently bulit apcu.so library:
In this file paste the following:
Restart Apache with the brew services stop httpd; brew services start httpd command to pick up your changes.
APCu for other PHP versions
For PHP 7.0 and above you can use the latest 5.x release of APCu, so the process is the same for all. First let's switch to PHP 7.0 and install the APCu library:
Restart Apache with the brew services stop httpd; brew services start httpd command to pick up your changes.
The uninstall -r enables PECL to only remove registration, it does not actually uninstall anything.
Again if you are OK with the ACPu defaults, you can leave things as-is, but you can choose to repeat the Optional APCu Configuration steps to create an APCu configuration file fore each PHP version.
For PHP 7.1, just repeat these steps but use 7.1 instead of 7.0:
For PHP 7.2:
For PHP 7.3:
For PHP 7.4:
With recent versions of Grav, we now make use of the native PECL YAML library that allow YAML processing to be done by highly efficient libYAML C library rather than by they Symfony PHP library. This can result in a 5X improvement in YAML processing times! Luckily this is a simple process to install for any PHP version:
Switch to PHP 5.6 mode, then run the following brew commands to install libyaml:
Then you can install YAML via PECL.
For PHP 5.6 we have to install the latest 1.3.x version of YAML, as this is the last version to provide PHP 5.6 support:
Answer any question by simply pressing Return to accept the default values
Restart Apache with the brew services stop httpd; brew services start httpd command to pick up your changes.
YAML for other PHP versions
For PHP 7.0 and above you can use the latest 2.x release of YAML, so the process is the same for all. First let's switch to PHP 7.0 and install the YAML library:
Restart Apache with the brew services stop httpd; brew services start httpd command to pick up your changes.
The uninstall -r enables PECL to only remove registration, it does not actually uninstall anything.
For PHP 7.1, just repeat these steps but use 7.1 instead of 7.0:
and for PHP 7.2:
and for PHP 7.3:
and again for PHP 7.4:
[Optional] YAML Configuration
If you are feeling adventurous, or you like to keep things uniform, you can follow the same procedure as APCu and remove the default extension-'yaml.so' entry in each PHP's php.ini and instead, create a conf.d/ext-yaml.ini file:
One of the most important aspects of any kind of development is the ability to debug and fix your code. PHP comes with limited support to dump variables or log to a file, but for more complex situations you need something more powerful.
Xdebug provides is a debugging and profiling extension for PHP that provides an HTML-friendly output for the var_dump() method that improves the readability of the default version. It also provides other useful dumping methods as well as displaying stack traces. One of the best features however, is the ability to remote debug your code. This means you can set breakpoints, and step through your PHP code inspecting as you go. Full documentation on Xdebug contains extensive information about all the functionality available.
Xdebug for various PHP versions
There are some compatibility issues we need to take into account, as certain versions of PHP can only run certain versions of Xdebug:
| PHP Version | Compatible Xdebug version |
|---|---|
| PHP 5.6 | Xdebug 2.5 |
| PHP 7.0 | Xdebug 2.7 |
| PHP 7.1 | Xdebug 2.9 |
| PHP 7.2+ | Xdebug 3.0 |
To install specific versions of Xdebug we need to switch to the PHP version we want to install it on, then run these commands:
For PHP 5.6
For PHP 7.0
For PHP 7.1
Install Apache Php Mysql Mac Catalina Update
For PHP 7.2+
change sphp 7.2 to the version you want to install xdebug for (from 7.2 to 8.0)
Xdebug Configuration
Like the other PECL-installed modules, this will create a simple entry in the php.ini file, but you really need to configure Xdebug for it to be useful. So let's just go ahead and create our configuration file as we'll need it shortly anyway.
You will now need to remove the zend_extension='xdebug.so' entry that PECL adds to the top of your php.ini. So edit this file and remove the top line. In this example we will use 5.6 but it's the same procedure for each version of PHP.
Once that line is removed, we can add a new file with a proper entry to the recently bulit xdebug.so library:
For Xdebug versions prior to 3.0 (ie, PHP 5.6 through PHP 7.1) you can paste the following into the file:
However, Xdebug version 3.0 (ie, PHP 7.2+) has a simplified syntax and should look like this:
Restart Apache with the brew services stop httpd; brew services start httpd command to pick up your changes. You should check the http://localhost/info.php to ensure that Xdebug information is displayed:
if Xdebug still shows up in php -v the most likely cause is you didn't remove the zend_extension='xdebug.so' entry at the top of php.ini
Restart Apache with the brew services stop httpd; brew services start httpd command to pick up your changes.
Xdebug Switcher Script
W00fz created a great tool for quickly enabling/disabling xdebug. Install this with brew:
Using it is simple, you can get the current state with:
And then turn it on or off with:
CLI Enabled Xdebug
There are times when you want to debug from the CLI, and you can do this by setting an environment variable. My preferred approach is to use a simple script that works with all versions of Xdebug. First create a file in your user's bin/ folder (create the folder if it doesn't already exist), and call it xdebug.conf then save this:
Then ensure it's executable:
Then when you need to debug, simply run it whenever you need it:
You should now be all set with a Rockin' PHP development environment! To find out how to enable SSL on Apache, check out Part 3 in the series.
NOTE: The brew installation actually creates configuration files in /usr/local/etc/php/5.6/conf.d, /usr/local/etc/php/7.0/conf.d, /usr/local/etc/php/7.1/conf.d, /usr/local/etc/php/7.2/conf.d, /usr/local/etc/php/7.3/conf.d, and /usr/local/etc/php/7.4/conf.d respectively. If you want to uninstall a PHP extension, simply rename the .ini file to .ini.bak and restart apache. Alternatively, you can simply use brew to uninstall it, and reinstall it again when you need it.
The following instructions assume a clean environment and show how to install PHP 8.0, the Microsoft ODBC driver, the Apache web server, and the Microsoft Drivers for PHP for SQL Server on Ubuntu, Red Hat, Debian, Suse, Alpine, and macOS. These instructions advise installing the drivers using PECL, but you can also download the prebuilt binaries from the Microsoft Drivers for PHP for SQL Server GitHub project page and install them following the instructions in Loading the Microsoft Drivers for PHP for SQL Server. For an explanation of extension loading and why we do not add the extensions to php.ini, see the section on loading the drivers.
The following instructions install PHP 8.0 by default using pecl install, if the PHP 8.0 packages are available. You may need to run pecl channel-update pecl.php.net first. Some supported Linux distros default to PHP 7.1 or earlier, which is not supported for the latest version of the PHP drivers for SQL Server. See the notes at the beginning of each section to install PHP 7.4 or 7.3 instead.
Also included are instructions for installing the PHP FastCGI Process Manager, PHP-FPM, on Ubuntu. PHP-FPM is needed if you're using the nginx web server instead of Apache.
While these instructions contain commands to install both SQLSRV and PDO_SQLSRV drivers, the drivers can be installed and function independently. Users comfortable with customizing their configuration can adjust these instructions to be specific to SQLSRV or PDO_SQLSRV. Both drivers have the same dependencies except where noted below.
Installing on Ubuntu
Ubuntu versions 16.04, 18.04, and 20.04 are supported.
Note
To install PHP 7.4 or 7.3, replace 8.0 with 7.4 or 7.3 in the following commands.
Step 1. Install PHP (Ubuntu)
Step 2. Install prerequisites (Ubuntu)
Install the ODBC driver for Ubuntu by following the instructions on the Install the Microsoft ODBC driver for SQL Server (Linux). Make sure to also install the optional unixodbc-dev package. It's used by the pecl command to install the PHP drivers.
Step 3. Install the PHP drivers for Microsoft SQL Server (Ubuntu)
If there is only one PHP version in the system, then the last step can be simplified to phpenmod sqlsrv pdo_sqlsrv.
Step 4. Install Apache and configure driver loading (Ubuntu)
Step 5. Restart Apache and test the sample script (Ubuntu)
To test your installation, see Testing your installation at the end of this document.
Installing on Ubuntu with PHP-FPM
Ubuntu versions 16.04, 18.04, and 20.04 are supported.
Note
To install PHP 7.4 or 7.3, replace 8.0 with 7.4 or 7.3 in the following commands.
Step 1. Install PHP (Ubuntu with PHP-FPM)
Verify the status of the PHP-FPM service by running:
Step 2. Install prerequisites (Ubuntu with PHP-FPM)
Install the ODBC driver for Ubuntu by following the instructions on the Install the Microsoft ODBC driver for SQL Server (Linux). Make sure to also install the optional unixodbc-dev package. It's used by the pecl command to install the PHP drivers.
Step 3. Install the PHP drivers for Microsoft SQL Server (Ubuntu with PHP-FPM)
If there is only one PHP version in the system, then the last step can be simplified to phpenmod sqlsrv pdo_sqlsrv.
Verify that sqlsrv.ini and pdo_sqlsrv.ini are located in /etc/php/8.0/fpm/conf.d/:
Restart the PHP-FPM service:
Step 4. Install and configure nginx (Ubuntu with PHP-FPM)
To configure nginx, you must edit the /etc/nginx/sites-available/default file. Add index.php to the list below the section that says # Add index.php to the list if you are using PHP:
Next, uncomment, and modify the section following # pass PHP scripts to FastCGI server as follows:
Step 5. Restart nginx and test the sample script (Ubuntu with PHP-FPM)
To test your installation, see Testing your installation at the end of this document.
Installing on Red Hat
Red Hat versions 7 and 8 are supported.
Step 1. Install PHP (Red Hat)
To install PHP on Red Hat 7, run the following commands:
Note
To install PHP 7.4 or 7.3, replace remi-php80 with remi-php74 or remi-php73 respectively in the following commands.
To install PHP on Red Hat 8, run the following commands:
Note
To install PHP 7.4 or 7.3, replace remi-8.0 with remi-7.4 or remi-7.3 respectively in the following commands.
Step 2. Install prerequisites (Red Hat)
Install the ODBC driver for Red Hat 7 or 8 by following the instructions on the Install the Microsoft ODBC driver for SQL Server (Linux). Make sure to also install the optional unixodbc-dev package. It's used by the pecl command to install the PHP drivers.
Step 3. Install the PHP drivers for Microsoft SQL Server (Red Hat)
You can alternatively install from the Remi repo:
Step 4. Install Apache (Red Hat)
SELinux is installed by default and runs in Enforcing mode. To allow Apache to connect to databases through SELinux, run the following command:
Step 5. Restart Apache and test the sample script (Red Hat)
To test your installation, see Testing your installation at the end of this document.
Installing on Debian
Debian versions 9 and 10 are supported.
Note
To install PHP 7.4 or 7.3, replace 8.0 in the following commands with 7.4 or 7.3.
Step 1. Install PHP (Debian)
Step 2. Install prerequisites (Debian)
Install the ODBC driver for Debian by following the instructions on the Install the Microsoft ODBC driver for SQL Server (Linux). Make sure to also install the optional unixodbc-dev package. It's used by the pecl command to install the PHP drivers.
You may also need to generate the correct locale to get PHP output to display correctly in a browser. For example, for the en_US UTF-8 locale, run the following commands:
You may need to add /usr/sbin to your $PATH, as the locale-gen executable is located there.
Step 3. Install the PHP drivers for Microsoft SQL Server (Debian)
If there is only one PHP version in the system, then the last step can be simplified to phpenmod sqlsrv pdo_sqlsrv. As with locale-gen, phpenmod is located in /usr/sbin so you may need to add this directory to your $PATH.
Step 4. Install Apache and configure driver loading (Debian)
Step 5. Restart Apache and test the sample script (Debian)
To test your installation, see Testing your installation at the end of this document.
Installing on Suse
Suse Enterprise Linux versions 12 and 15 are supported.
Note
In the following instructions, replace <SuseVersion> with your version of Suse. If you are using Suse Enterprise Linux 15, it will be SLE_15_SP1 or SLE_15_SP2. For Suse 12, use SLE_12_SP4 (or above if applicable). Not all versions of PHP are available for all versions of Suse Linux. Refer to http://download.opensuse.org/repositories/devel:/languages:/php to see which versions of Suse have the default version of PHP available, or check http://download.opensuse.org/repositories/devel:/languages:/php:/ to see which other versions of PHP are available for which versions of Suse.
Note
Packages for PHP 7.4 or above are not available for Suse 12 and Package for PHP 8.0 is not yet available for Suse 15.To install PHP 7.3, replace the repository URL below with the following URL:https://download.opensuse.org/repositories/devel:/languages:/php:/php73/<SuseVersion>/devel:languages:php:php73.repo.
Step 1. Install PHP (Suse)
Step 2. Install prerequisites (Suse)
Install the ODBC driver for Suse by following the instructions on the Install the Microsoft ODBC driver for SQL Server (Linux). Make sure to also install the optional unixodbc-dev package. It's used by the pecl command to install the PHP drivers.
Step 3. Install the PHP drivers for Microsoft SQL Server (Suse)
Note
If you get an error message saying Connection to 'pecl.php.net:443' failed: Unable to find the socket transport 'ssl', edit the pecl script at /usr/bin/pecl and remove the -n switch in the last line. This switch prevents PECL from loading ini files when PHP is called, which prevents the OpenSSL extension from loading.
Step 4. Install Apache and configure driver loading (Suse)
Step 5. Restart Apache and test the sample script (Suse)
To test your installation, see Testing your installation at the end of this document.
Installing on Alpine
Alpine versions 3.11 and 3.12 are supported.
Note
The default version of PHP is 7.3. PHP 7.4 or above may be available from testing or edge repositories for Alpine. You can instead compile PHP from source.
Step 1. Install PHP (Alpine)
PHP packages for Alpine can be found in the edge/community repository. Check Enable Community Repository on their WIKI page. Add the following line to /etc/apk/repositories, replacing <mirror> with the URL of an Alpine repository mirror:
Then run:
Step 2. Install prerequisites (Alpine)
Install the ODBC driver for Alpine by following the instructions on the Install the Microsoft ODBC driver for SQL Server (Linux). Make sure to also install the unixodbc-dev package (sudo apk add unixodbc-dev). It's used by the pecl command to install the PHP drivers.
Step 3. Install the PHP drivers for Microsoft SQL Server (Alpine)
Step 4. Install Apache and configure driver loading (Alpine)
Step 5. Restart Apache and test the sample script (Alpine)
To test your installation, see Testing your installation at the end of this document.
Installing on macOS
MacOS versions 10.14 (Mojave), 10.15 (Catalina), and 11.0 (Big Sur) are supported.
If you do not already have it, install brew as follows:
Note
To install PHP 7.4 or 7.3, replace php@8.0 with php@7.4 or php@7.3 respectively in the following commands.
Step 1. Install PHP (macOS)
PHP should now be in your path. Run php -v to verify that you are running the correct version of PHP. If PHP is not in your path or it is not the correct version, run the following commands:
Step 2. Install prerequisites (macOS)
Install the ODBC driver for macOS by following the instructions on the Install the Microsoft ODBC driver for SQL Server (macOS).
In addition, you may need to install the GNU make tools:
Step 3. Install the PHP drivers for Microsoft SQL Server (macOS)
Step 4. Install Apache and configure driver loading (macOS)
To find the Apache configuration file, httpd.conf, for your Apache installation, run:
The following commands append the required configuration to httpd.conf. Be sure to substitute the path returned by the preceding command in place of /usr/local/etc/httpd/httpd.conf:
Step 5. Restart Apache and test the sample script (macOS)
To test your installation, see Testing your installation at the end of this document.
Testing Your Installation
To test this sample script, create a file called testsql.php in your system's document root. This path is /var/www/html/ on Ubuntu, Debian, and Red Hat, /srv/www/htdocs on SUSE, /var/www/localhost/htdocs on Alpine, or /usr/local/var/www on macOS. Copy the following script to it, replacing the server, database, username, and password as appropriate.
SQLSRV example
PDO_SQLSRV example
Point your browser to https://localhost/testsql.php (https://localhost:8080/testsql.php on macOS). You should now be able to connect to your SQL Server/Azure SQL database. If you don't see a success message showing SQL version information, you can do some basic troubleshooting by running the script from the command line:
If running from the command line is successful but nothing shows in your browser, check the Apache log files. For more help, see Support resources for places to go.