einserver.de

Using the build-in Apache in Mac OS X for PHP and Virtual Hosts

A collection of all steps necessary to use the Apache server
that ships with Mac OS X for web development with PHP and virtual hosts.

This guide is split into five simple steps.

1. Enabling PHP on Mac OS X
2. Enabling .htaccess files
3. Enabling Virtual Hosts
4. Configure Virtual Hosts
5. Control Apache

Before you start

You will have to run some commands on Terminal.app. I also recommend that you use a good code editor like TextMate which can be launched from the command line and override files with Administrator permissions. To browse hidden directories in the Finder.app you able to use the Go to folder-Command and enter the path there or use the Terminal.app and the open command.

We will edit three files:

• /etc/apache2/httpd.conf - contains the general Apache settings
• /etc/apache2/extra/httpd-vhosts.conf - contains our virtual hosts
• /etc/hosts - for routing our development domains

Remember to make backups. Anfema is not responsible for any damage or anything that goes wrong. If you don't know what you are doing and don't want to risk something to learn new things, try this or simply hire us!

1. Enabling PHP on Apache for Mac OS X

Open httpd.conf, and look for this line:

#LoadModule php5_module libexec/apache2/libphp5.so 

Remove the # in front of that line to uncomment and enable it.

Look for

#
# DirectoryIndex: sets the file that Apache will serve if a directory
# is requested.
#
<IfModule dir_module>
    DirectoryIndex index.html
</IfModule>

and add index.php after index.html.

2. Enabling .htaccess files

The .htaccess control files allow you to adjust the configuration of your Apache for a single directory and are often used to support url rewrites and other useful features. By default, the Apache in OS X is configured to ignore most of the settings in them, so you have to unlock those features first. Look into the httpd.conf and find this block - it's above the DirectoryIndex block you edited before.

<Directory />
    Options FollowSymLinks
    AllowOverride None
    Order deny,allow
    Deny from all
</Directory>

Change AllowOverride None to AllowOverride All.

Now look a bit further down the file, right below that block there is another directory rule:

<Directory "/Library/WebServer/Documents">
    ...

Change the AllowOverride in there to All, too.

Now you can use an .htaccess file in your upcoming virtual host to adjust settings a runtime and without restarting Apache.

3. Enabling Virtual Hosts

Still in httpd.conf look for the following line and as before remove that # in front of the line to enable it

# Virtual Hosts
#Include /private/etc/apache2/extra/httpd-vhosts.conf

If you want to use the Apache without enabling Apples Websharing (see Point 5), remember to move the Include directive you just edited. outside the block <IfDefine WEBSHARING_ON>, which means after </IfDefine> a few lines below.

Now open httpd-vhosts.conf. You will find two examples and some other configuration there. It's totally save to leave that stuff there, but if it gives you peace of mind, you can comment our every line except this one:

NameVirtualHost *:80

To allow virtual hosts outside /Library/WebServer/Documents/ or ~/Sites/, which can be handy if you want to use a repository on your other disk as the document directory for your virtual host, you have to add the following lines for every directory you want to use. You can use * as wildcard. This can be helpful, if you would want to allow something like this.

# Enable Repositories folder for every user on the system as possible document root location
<Directory "/Users/*/Repositories/">
    Options Indexes Includes FollowSymLinks SymLinksifOwnerMatch ExecCGI MultiViews
    AllowOverride All
    Order allow,deny
    Allow from all
</Directory>

You might add the following code at the end of the file to re-enable the default document root.

<VirtualHost *:80>
    DocumentRoot "/Library/WebServer/Documents"
    ServerName localhost
</VirtualHost>

4. Configuring Virtual Hosts

Every virtual host you want to add needs two steps. You need to add the virtual host configuration and you need to link the virtual host to a domain. I strongly suggest you use .dev instead of a regular tld so you can differentiate better between local and online projects.

First in httpd-vhosts.conf add the configuration for your virtual host.

# An amazing project
<VirtualHost *:80>
    DocumentRoot "/Users/anfemademo/Repositories/amazingproject"
    ServerName amazingproject.dev
</VirtualHost>

Now your Apache recognizes your virtual host when you try to reach it under the ServerName/hostname amazingproject.dev

Now in /etc/hosts add the following line at the end to route any requests to amazingproject.dev to your localhost and therefore your Apache.

127.0.0.1 amazingproject.dev

Phew, that's it! Now you should have a proper configuration and it's time to start your Apache.

5. Controlling Apache

Until Mac OS X Lion (10.7) Apple included Web Sharing in the System Preferences, which gave you a basic interface for starting and stopping the server. This feature was removed from Mountain Lion (10.8), so you will have to use the Terminal command. Use sudo apachectl -k <command> with <command> being start, stop or restart.

Now that you have startet your Apache, you can open your browser and surf to http://amazingproject.dev. If everything worked out, you should see your project running. You should type in the whole thing, including the http:// part, as some browsers ignore your hosts file for the url-autocompletion.

If it doesn't work, check Console.app for any Apache or other errors and check the three files we edited for typos.

Bonus

You should check out Homebrew, which is an excellent package manager for Mac OS X and makes it super easy to install additional server tools like MySQL.

Happy coding.