There are multiple methods and tools for developing web applications locally, I’ve always been a big fan of MAMP Pro due to it’s simplicity and it’s UI, it’s pleasant to use, very easy to setup and you’ll get running in no time. It does however have it’s downfalls and with OS X 10.11 now coming bundled with Apache what better time to try a new setup.
Note: This method is experimental only, when you upgrade the OS X you may loose your settings. Please use the following with caution.
When using third party programs you depend on it to have the latest versions of the development stack, but it can become out of date. By not using third party software you have full control over your setup, today I’ll be giving you a deep dive on how to setup your environment with the ability to have multiple PHP versions and virtual hosts. This article is for experienced developers who have experience using the command prompt.
Files you’ll be editing
To keep things simple I’ve listed out all the files you’ll need:
/private/etc/hosts /etc/apache2/httpd.conf /etc/apache2/extra/httpd-vhosts.conf
Step 1: Apache commands
As Apache is already installed you can start getting familiar with its commands straight away by opening up the command prompt and entering the following.
Start:
sudo apachectl start
Stop:
sudo apachectl stop
Restart:
sudo apachectl restart
Apache version:
httpd -v
After starting Apache you can test to see if the server is working in the browser by going to http://localhost you should see the text “It works!”. If your struggling to reach your site via this url you might need to add an alias in your /private/etc/hosts file, even though it should be there by default. Simply add 127.0.0.1 localhost on a new line and save.
Note: Throughout the rest of this article whenever you see the string your_username being used please change it to match the username on your Mac.
Step 2: Configuring Apache
Now you have tested the server is working you need to configure it. To do this you need to open up the /etc/apache2/httpd.conf file in your favorite text editor. Before you do though make a quick backup just in case you make an error you can always revert to the original:
cp /etc/apache2/httpd.conf /etc/apache2/httpd.conf.backup
Now you have a backup you can go in and edit the file, I’ll be using the vim tool in my examples:
vim /etc/apache2/httpd.conf
There will be multiple areas you need to change in this file but I’ll break it down into small chunks detailing what each part does.
Enable modules and includes
The first set of configuration will be to enable some modules and an include which I’ve listed out below, to enable them simply remove the # symbol from the beginning of the line:
Search for the term vhost_alias_module:
LoadModule vhost_alias_module libexec/apache2/mod_vhost_alias.so
Search for the term rewrite_module:
LoadModule rewrite_module libexec/apache2/mod_rewrite.so
Search for the term php5_module:
LoadModule php5_module libexec/apache2/libphp5.so
Search for the term Virtual hosts:
Include /private/etc/apache2/extra/httpd-vhosts.conf
Some applications require the mod_rewrite module which provides a rule-based rewriting engine to rewrite requested URLs on the fly.
While Virtual Hosts allow you to run more than one website on a single machine, you can also point them to individual IP addresses or domain names of your choice which I’ll cover in more depth later on.
Document root
This is the directory where you’ll be serving your documents from, it’s entirely down to personal preference, traditionally it’s named public_html or htdocs. In this example we’ll be pointing it to a new folder called Sites under our username.
Search for the term DocumentRoot and change the path so it reads:
DocumentRoot "/Users/your_username/Sites"
You’ll also need to change the <Directory> tag on the line below to the same path:
<Directory "/Users/your_username/Sites">
Within the same <Directory> block change the AllowOverride setting to read:
AllowOverride All
This setting will allow any .htaccess files to override the default settings.
User and group
Apache is now pointing to your Sites folder, however you also need to tell Apache to run under a different username and group otherwise you will face permission problems when trying to access the files in your home directory. By default Apache runs under the _www username and the _www group.
Search for the term User _www and change it to read:
User your_username Group staff
Notice the Group is set to staff this is because all users are members of the staff group. If your user is setup differently you may have to change this parameter to your individual requirements. A quick and easy way to see what group your username is assigned to is by running ls -la within the home directory in the command prompt which will display the group column against your folders and files.
Directory index
You’ll need to add index.php to your directory index which sets the files that Apache will serve if a directory is requested.
Search for the term <IfModule dir_module> and change it to read:
<IfModule dir_module>
DirectoryIndex index.html index.php
</IfModule>
Don’t forget to save the file at this stage, you’ll be coming back to this file shortly.
Create a sites folder
Now that you have your initial configuration in place you need to create your Sites folder to house your documents. You’ll also create your first html file to ensure everything is working as intended:
mkdir ~/Sites echo '<h1>Hello World!</h1>' > ~/Sites/index.html
You now need to restart apache so that your changes will take effect, it’s important to note that whenever a change is made it won’t take effect until Apache is restarted.
sudo apachectl restart
Now if you open up your browser and head to http://localhost you should see the message you created.
PHP info
It’s also a good time to check that PHP is working. The easiest way to do this is by using the built in phpinfo() which will detail out your PHP configuration including what version your using:
cd ~/Sites echo "<?php phpinfo(); ?>" > ~/Sites/info.php
If you open up your browser and head to http://localhost/info.php you should see the PHP configuration.
If this is working you can proceed with the next step, if not you’ll need to backtrack through the configuration and ensure it’s all correct.
Step 3: MySQL
MySQL is a missing component in OS X 10.11 and needs to be dowloaded from the MySQL site or alternatively for ease of use you can install it through Homebrew. Either installation method will work, however in this article I’ll be showing you how to install it through Homebrew.
First you need to install Homebrew if you haven’t already:
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
To check everything is running correctly you can run:
brew doctor
If you have Homebrew already installed ensure its all up to date by running:
brew update
Now you can go ahead and install MySQL by running:
brew install mysql
It’s that simple! You can then use the following commands to run MySQL:
Start:
mysql.server start
Stop:
mysql.server stop
Restart:
mysql.server restart
When working with databases I always find it useful to use a GUI and would recommend downloading Sequel Pro (it’s free) which provides an easy to use interface.
Remember to make sure your MySQL server is running otherwise you won’t be able to connect.
Step 4: Virtual hosts
Earlier you loaded in the necessary modules for virtual hosts, you now need to configure these by opening the following file:
vim /etc/apache2/extra/httpd-vhosts.conf
This file already contains some instructions for you, it’s important to note that these entries are matched in order. Because you changed your DocumentRoot earlier you need to add in support for this as your first entry:
<VirtualHost *:80>
DocumentRoot "/Users/your_username/Sites"
ServerName localhost
</VirtualHost>
You can then add further entries below like so:
<VirtualHost *:80>
DocumentRoot "/Users/your_username/Sites/my-site"
ServerName my-site.com
</VirtualHost>
When adding entries into your virtual hosts file you will also need to add them into your Mac hosts file. To do this open up the following file:
vim /private/etc/hosts
In here you’ll need to add a new entry that matches your ServerName from the virtual hosts file and then save:
127.0.0.1 my-site.com
Lastly you need to restart apache so that your virtual host entries take effect:
sudo apachectl restart
Navigating to my-site.com should now display your website. You’ll have to add a index.html or index.php file within the /Users/your_username/Sites/my-site/ folder otherwise you’ll just get nothing showing.
That sums up the standard setup for a localhost environment. If you want to be able to manage multiple PHP versions and enable additional features like SSI (Server Side Includes) keep on reading below where I’ll be covering these topics.
Multiple PHP versions
Having a flexible localhost environment is key when your working with multiple applications as each have their own prerequisite. We can utilise Homebrew by installing multiple PHP versions and switching between them as needed.
Homebrew has a selection of PHP versions we can pick from, of course you can choose which versions you want to install. Before we do there are a few dependencies that are required which are outlined on their GitHub page, simply enter the following into the command prompt:
brew tap homebrew/dupes brew tap homebrew/versions brew tap homebrew/homebrew-php
Now you can install the individual PHP versions like so:
brew install php55 brew unlink php55 brew install php56 brew unlink php56
You will notice the unlink option which will allow you to use multiple PHP versions. The last step is to link Apache to the PHP version you want to use. To do this you need to open up /etc/apache2/httpd.conf and search for the term php5_module which needs commenting out like so:
#LoadModule php5_module libexec/apache2/libphp5.so
Right below this line we can add in our own, remember to only have 1 of them un-commented at a time:
# Brew PHP LoadModule, Edited LoadModule php5_module /usr/local/opt/php55/libexec/apache2/libphp5.so #LoadModule php5_module /usr/local/opt/php56/libexec/apache2/libphp5.so
As you have edited the Apache configurtion you’ll now need to restart Apache so that your changes take effect:
sudo apachectl restart
Each time you need to use a different version of PHP simply open up this file and amend as necessary.
Enabling SSI
To enable SSI there are a couple of extra configuration settings you need to add to Apache. First load in the mod_include module, to enable it simply remove the # symbol from the beginning of the line.
Search for the term include_module:
LoadModule include_module libexec/apache2/mod_include.so
Don’t forget to save the file. Next you need to configure Apache to parse .shtml files. This will allow the server to process content server side before its sent to the client. To do this you add the configuration to your .htaccess file within your site folder.
Create a .htaccess file if you don’t already have one within:
/Users/your_username/Sites/my-site/
Then open up the file and enter the following configuration and save:
AddType text/html .shtml AddHandler server-parsed .html AddHandler server-parsed .shtml Options Indexes FollowSymLinks Includes
Now we just need to restart apache and everything should be working as expected:
sudo apachectl restart
Tips
There are a lot of commands and paths in the command prompt to remember which can be tricky when you’re first starting out. To overcome this I use alias which allows me to assign shortcuts for common commands. These are added into your .bash_profile located in your home directory.
If you don’t already have one you can easily create one by entering the following into the command prompt:
cd ~/ touch .bash_profile
Now you can enter your alias, below is an example of how my .bash_profile looks, you’ll notice I’m using Sublime Text to open up my files:
# Ensure user-installed binaries take precedence export PATH=/usr/local/bin:$PATH # Alias alias hosts='sublime /private/etc/hosts' # Server alias alias apache-httpd='sublime /etc/apache2/httpd.conf' alias apache-vhosts='sublime /etc/apache2/extra/httpd-vhosts.conf' alias apache-start='sudo apachectl start' alias apache-stop='sudo apachectl stop' alias apache-restart='sudo apachectl restart' alias mysql-start='mysql.server start' alias mysql-stop='mysql.server stop' alias mysql-restart='mysql.server restart'
Once saved you might need to re-start the command prompt. Then to run the command you simply type in the alias name for example:
apache-start
Wrap up
Hopefully you’re now set up! It can be a little daunting when configuring a server for the first time which is why it’s always good practice to make backups of files when doing something like this. However it’s a rewarding exercise and once it’s setup you’ll barely touch it again, plus you gain an insight into how Apache servers are setup.