Enable Apache and PHP5 on Mac OSX Leopard

Apache and PHP are there... just turn them on!

Author: M Butcher
Date: 2008-05-28 12:56:36 -0400

Apple's OS X Leopard (10.5) comes with the Apache web server and PHP 5 pre-installed. But by default neither one is enabled. This short guide tells you how to get started.

Apache

OS X Leopard ships with Apache 2.2 preconfigured for "sharing documents". In this configuration, each user on your system has a Sites/ directory inside of their home directory. (Example: /Users/mbutcher/Sites/)

Turning Apache On

By default, Apache is turned off. That means that when you start up your system, Apache is not one of the services started. To start it, got to your System Preferences, click on Sharing, and then check the Web Sharing checkbox in the list of services.

Alternatively, you may wish to start and stop Apache from the command line (I do this a lot when configuring Apache). This, too, is simple. Open up a Terminal session (Terminal is one of the Untilities that comes with OS X). To start Apache, use this command:

$ sudo apachectl start

(Note that hte $ sign is just there to indicate the shell prompt. You do not need to type $.)

This will prompt you to enter a password, and will then (as root) attempt to start Apache. In a nutshell, we are using the apachectl (short for Apache Control) program to tell Apache to start.

To stop Apache, we also use apachectl:

$ sudo apachectl stop

Similarly, we can restart Apache (to, say, reload config files) with this command:

$ sudo apachectl restart

This will stop and start Apache again, reloading the configuration files as it goes.

Adding Content

Now that Apache is running, you probably want to add some content. Here's how this is done.

Each user can store web content in the Sites/ directory an make it accessible to other users on the local network (the LAN). Content in the Sites/ folder will then be accessible using a URL like this: http://HOSTNAME/~USERNAME/FILENAME. Here, HOSTNAME should be replaced with the name or IP address of the computer, USERNAME should be the username of the user on the Mac, and FILENAME should be the file to access.

For example, here's a URL to a test page of mine:

http://matthew-butchers-macbook-pro.local/~mbutcher/test.html

Since I have a file in /Users/mbutcher/Sites/test.html, the URL above will retrieve that file and display it in a web browser. If the test.html file did not exist, an error message (File Not Found) would be displayed in my web browser.

PHP 5

PHP 5 -- both the command line version and the Web server module -- are installed by default in OS X Leopard. To verify this, you can open a Terminal and type:

$ which php

This will print out the path to the version of PHP installed:

/usr/bin/php

To find out more about this version of PHP, try this:

$ php --version

This will print out version information:

PHP 5.2.5 (cli) (built: Feb 20 2008 12:30:47) 
Copyright (c) 1997-2007 The PHP Group
Zend Engine v2.2.0, Copyright (c) 1998-2007 Zend Technologies

So we have PHP installed and available... but how do we configure Apache to allow it?

Enable the PHP Apache Module

To get Apache to process PHP pages, we need to make one minor change to one of Apache's configuration file. We need to edit /etc/apache2/httpd.conf. And we will do this in Terminal by entering the following command:

$ sudo pico /etc/apache2/httpd.conf

(You might want to make a copy of /etc/apache2/httpd.conf first. Do that like this: cp /etc/apache2/httpd.conf /etc/apache2/original-httpd.conf.)
This will (as root) open up the httpd.conf file in the pico command-line editor. Other editors, like vi and emacs, are available if you prefer them.

Scroll down through the file until you locate a line that looks like this:

#LoadModule php5_module libexec/apache2/libphp5.so

It is a few hundred lines into the file, and it is just below a dozen or so other lines that also start LoadModule. All you need to do is remove the leading hash mark (#). The finished line should look like this:

LoadModule php5_module libexec/apache2/libphp5.so

Save and exit (hit Control-X in pico).

Now restart Apache:

$ sudo apachectl restart

At this point, you should have PHP enabled.

To test things out, you can create a file in /Users//Sites/test.php that looks like this:

Then access it in your browser with http://localhost/~YOURNAME/test.php. You should simply see the words This is a test.

Common Problems

1. Access Denied Errors: If you get access denied errors, then you may need to fix the permissions on you Sites directory. From a Terminal window, you can run this command: chmod -R 755 /Users/YOURNAME/Sites.
2. Error Connecting to Server: If you are getting errors that tell you the site is unavailable or that the browser cannot connect to the server, chances are good that Apache is not started. Use this command: sudo apachectl restart.
3. Starting Apache Fails: If there is an error starting Apache, chances are good that you made a mistake when editing httpd.conf file. Read back over that section. If you made a backup copy, then you can always restore from there, or use the diff command to see what you changed.
4. The version of PHP included with OS X does not include one or more modules that you need: At this point, it appears that the solution to this is... to build PHP from source.

Of course, there are other things that can go wrong. Fortunately, once you have the webserver running, you should be able to access all of Apache's documentation by typing in this URL: http://localhost/manual/

If you are somewhat familiar with Apache, you might know already that the type of configuration that allows us to map Sites directories to URLs is the "Per-user Web Directories (public_html)" configuration. There are many resources (including the Apache docs) that explain the details of this system.

Finally, if you are looking for the rest of the configuration files for Apache, most of them are located in /etc/apache2/. The ones in the other/ directory are loaded automatically. The ones in extra/ may or may not be loaded. You'll have to check the httpd.conf file to find out.