HOWTO: Setup PHP, Apache and MySQL development environment on OS X Snow Leopard

UPDATED: Updated to use PHP 5.3.1 and with easier instructions for fixing PHP’s iconv linking problem via Apple’s iconv.patch file.

Although Mac OS X Snow Leopard (10.6) finally comes with current versions of open source software developers use, the default setup is not enough for our needs so we’ve compiled this easy to follow guide to setting up a PHP development environment including the following:

• PHP 5.3
• Apache 2.2
• MySQL 5.1

As I mentioned, we needed to add a few things to the PHP install that Apple left out:

• GeoIP
• libjpeg
• libpng
• IMAP
• libmcrypt
• gettext

Setup a place for your source code

First, you need to setup a place to store all the stuff you’re going to be downloading.


mkdir ~/src

Install MaxMind’s GeoLite

This optional install allows you to use PHP’s GeoIP functions to do basic IP-based location of your site’s visitors.


cd ~/src/
curl -O http://geolite.maxmind.com/download/geoip/api/c/GeoIP.tar.gz
tar -xzf GeoIP.tar.gz
cd GeoIP-*
./configure
make -j3
sudo make install

Add the free GeoLite City Database


cd ~/src/
curl -O http://geolite.maxmind.com/download/geoip/database/GeoLiteCity.dat.gz
gunzip GeoLiteCity.dat.gz
sudo mv GeoLiteCity.dat /usr/local/share/GeoIP/ UPDATE: I discovered that PHP’s GeoIP functions don’t seem to like the GeoLiteCity.dat filename so we need to make the Lite version appear as if it were the full version.
sudo ln -s /usr/local/share/GeoIP/GeoLiteCity.dat /usr/local/share/GeoIP/GeoIPCity.dat

Install Apache 2.2

This will install a completely separate instance of Apache 2.2 than the Apple supplied version. This way you never have to worry about a Software Update overwriting or messing up your customized setup. The best part about this method is that you can still use the Sharing Preference Pane to start and stop your version of Apache.


cd ~/src/
curl -O http://www.reverse.net/pub/apache/httpd/httpd-2.2.13.tar.gz
tar -xzf httpd-2.2.13.tar.gz
cd httpd-2.2.13

We will install this version of Apache 2.2 at the root level of your hard drive /apache2. If you prefer to put it elsewhere just change the --prefix= option to where you want it. You will also need to make changes in some of the other commands below, including the configuration for PHP.


./configure \
--prefix=/apache2 \
--with-php \
--with-mysql \
--enable-rewrite \
--enable-speling \
--enable-ssl \
--enable-deflate \
--enable-mods-shared=all \
--with-included-apr

In every case where we use make you will notice that we use make -j3. This specifies to use 3 jobs during the make. An easy rule of thumb is to use the number of processor cores your machine has +1. If you have a Mac Pro, you can use make -j9 throughout these instructions.


make -j3
sudo make install

Make Your Apache Installation Play Nice With OSX

This part will allow you to stop/start your Apache using the Sharing Preference Pane. If you find that your setup doesn’t work correctly after installing an Apple Software Update or Security Update, simply repeat this section to “repair” your setup.


sudo cp -p /usr/sbin/apachectl /apache2/bin/apachectl
sudo mv /usr/sbin/apachectl /usr/sbin/apachectl-orig
sudo mv /usr/sbin/httpd /usr/sbin/httpd-orig
sudo mv /usr/sbin/envvars /usr/sbin/envvars-orig
sudo ln -s /apache2/bin/apachectl /usr/sbin/apachectl
sudo ln -s /apache2/bin/httpd /usr/sbin/httpd
sudo ln -s /apache2/bin/envvars /usr/sbin/envvars

Add VirtualHosts to Make Your Development Easy

We prefer to have each developer use their own VirtualHost for development and we create them in the form developername.projectname.dev. If you use this method you will need to add each of these hosts to your /etc/hosts file making sure not to mess with the existing top portion of the file.


sudo pico /etc/hosts

Add in yours in the following format.


##
# Development "hosts"
127.0.0.1 tom.teamonetickets.dev
127.0.0.1 tom.anotherproject.dev

You will also need to setup VirtualHosts within your Apache conf files for each one that you wish to use. Additionally, you will want to make sure to enable PHP by editing the configuration file at /apache2/conf/httpd.conf.


sudo pico /apache2/conf/httpd.conf

Uncomment the LoadModule line for PHP by changing
#LoadModule php5_module modules/libphp5.so to
LoadModule php5_module modules/libphp5.so (If this line is missing, you may need to wait until after you have completed the PHP installation.)

Then scroll to the bottom of the file and add the following:


<IfModule mod_php5.c>
    # If php is turned on, we repsect .php and .phps files.
    AddType application/x-httpd-php .php .html
    AddType application/x-httpd-php-source .phps

    # Since most users will want index.php to work we also enable index.php
    <IfModule mod_dir.c>
        DirectoryIndex index.html index.php
    </IfModule>
</IfModule>

Lastly, for development we prefer to actually use the Sites folder in our home directories to serve sites from so we will symlink it to where Apache is looking. (This won’t work well if you have multiple developers on the same machine with different user accounts.)


sudo rm -r /apache2/htdocs
sudo ln -s ~/Sites /apache2/htdocs

Fritz Stelluto pointed out that going this route may prevent CGI scripts from executing. If you need that ability you may prefer to just change the DocumentRoot in the httpd.conf.

Install libjpeg

If you’re going to be manipulating images you will probably want to install libjeg. These instructions are adapted from the instructions at Agile Animal Inc.


cd ~/src/
curl -O http://www.ijg.org/files/jpegsrc.v7.tar.gz
tar xfz jpegsrc.v7.tar.gz
cd jpeg-*
ln -s `which glibtool` ./libtool

./configure \
--enable-shared \
--prefix=/usr/local/libjpeg

make -j3
sudo mkdir -p /usr/local/libjpeg/include
sudo mkdir -p /usr/local/libjpeg/lib
sudo mkdir -p /usr/local/libjpeg/bin
sudo mkdir -p /usr/local/libjpeg/man/man1
sudo make install

Install libpng

If you’re going to be manipulating images you will probably also want to install libpng. These instructions are also adapted from the instructions at Agile Animal Inc.


cd ~/src/
curl -L -O 'http://prdownloads.sourceforge.net/libpng/libpng-1.2.38.tar.gz'
tar xzf libpng-1.2.38.tar.gz
cd libpng-1*

./configure \
--enable-shared \
--prefix=/usr/local/libpng

make -j3
sudo make install

Install IMAP c-client Libraries

You will need these if you ever want to have PHP access an IMAP mailbox, such as your Gmail.


cd ~/src/
curl -O ftp://ftp.cac.washington.edu/imap/imap.tar.Z
tar -xzf imap.tar.Z
cd imap*

Some HOWTOs out there tell you to use make oxp, which worked on OS X Leopard (10.5), but does not work on Snow Leopard (10.6)


make osx

We will need to have some of the c-client files in a place where our PHP configure will look for them. Use a little something found over at the Forums MacBidouille.


sudo cp c-client/*.h /usr/local/include/
sudo cp c-client/c-client.a /usr/local/lib/libc-client.a

Install libmcrypt

Mcrypt/libmcrypt “allows developers to use a wide range of encryption functions, without making drastic changes to their code.”


cd ~/src/
curl -L -O http://downloads.sourceforge.net/project/mcrypt/Libmcrypt/2.5.8/libmcrypt-2.5.8.tar.gz
tar -xzf libmcrypt-2.5.8.tar.gz
cd libmcrypt*

The PHP Manual says to disable-posix-threads.


./configure \
--disable-posix-threads

make -j3
sudo make install

Install gettext

From the gettext homepage: “The GNU `gettext' utilities are a set of tools that provides a framework to help other GNU packages produce multi-lingual messages.” These instrustions were adapted from Imthiaz Blog.


cd ~/src/
curl -O ftp://ftp.gnu.org/gnu/gettext/gettext-0.17.tar.gz
tar -xzf gettext-0.17.tar.gz
cd gettext-0.17/gettext-tools
./configure
make -j3
sudo make install

Install PHP 5.3 on Snow Leopard


cd ~/src/
curl -O -L http://us.php.net/get/php-5.3.1.tar.gz/from/www.php.net/mirror
tar -xzf php-5.3.1.tar.gz
cd php-5.3.1

./configure \
--prefix=/usr/local/php5 \
--mandir=/usr/share/man \
--infodir=/usr/share/info \
--sysconfdir=/private/etc \
--with-apxs2=/apache2/bin/apxs \
--enable-cli \
--with-libxml-dir=/usr \
--with-openssl=/usr \
--with-kerberos=/usr \
--with-zlib=/usr \
--enable-bcmath \
--with-bz2=/usr \
--enable-calendar \
--with-curl=/usr \
--enable-exif \
--enable-ftp \
--with-gd \
--with-jpeg-dir=/usr/local/libjpeg \
--with-png-dir=/usr/local/libpng \
--enable-gd-native-ttf \
--with-ldap=/usr \
--with-ldap-sasl=/usr \
--enable-mbstring \
--enable-mbregex \
--with-mysql=mysqlnd \
--with-mysqli=mysqlnd \
--with-pdo-mysql=mysqlnd \
--with-mysql-sock=/tmp/mysql.sock \
--with-iodbc=/usr \
--enable-shmop \
--with-snmp=/usr \
--enable-soap \
--enable-sockets \
--enable-sysvmsg \
--enable-sysvsem \
--enable-sysvshm \
--with-xmlrpc \
--with-iconv-dir=/usr \
--with-xsl=/usr \
--with-pcre-regex \
--with-imap \
--with-imap-ssl \
--with-mcrypt \
--with-mhash \
--with-freetype-dir=/usr/X11 \
--enable-zend-multibyte \
--with-gettext \
--with-pear \
--disable-debug

Now, we need to work around a bug with inconv linking. Luckily, Apple provides a patch. Either copy the text of that patch and save it as a file or download it here.


curl -O //www.teamonetickets.com/software/iconv.patch
patch -p1 < iconv.patch

Now that iconv will link properly, continue with our make.


make -j3

Be a good open source user and make test and submit your results to the PHP developers. This will take about 10-15 minutes, so go grab a beer and wait.


make test

After you have submitted your test results, finish by installing.


sudo make install

Add the GeoIP PECL Extension


sudo pecl channel-update pecl.php.net
sudo pecl install geoip

Setup Your php.ini

Copy php.ini-development into place. Many new options and documentation have been added in PHP 5.3 so I suggest that you diff your previous version and make sure you copy over any necessary changes you have made.


sudo cp php.ini-development /usr/local/php5/lib/php.ini

You will also need to make adjsutments to your php.ini for the geoip features. In the “Dynamic Extensions” section add
extension=geoip.so

In the “Module Settings” section add
[geoip]
; Directory where GeoIP databases are installed
geoip.custom_directory = /usr/local/share/GeoIP

While you are editing your php.ini don't forget to set your time zone. It is required with PHP 5.3. Choose a time zone from this list.


date.timezone = "America/Phoenix"

Grab a Copy of Zend Framework

If you're a Zend Framework user you may want to go ahead and put a copy of it into your PHP environment. If you’re not sure where you want to put it you should check out Sam Hennessy’s Zend Framework - “Location, Location Location!” This will install Zend Framework 1.9.7.


sudo svn export -r 20156 http://framework.zend.com/svn/framework/standard/trunk/library/Zend /usr/local/php5/lib/php/Zend --force

Install and Configure MySQL 5.1

Download and install the MySQL 5.1 package for “Mac OS X 10.5 (x86_64).” It works fine with Snow Leopard.


cd ~/src/
curl -OL http://opensource.become.com/mysql/Downloads/MySQL-5.1/mysql-5.1.37-osx10.5-x86_64.dmg

Do not install the Preference Pane or the StartupItem. We will control MySQL with a “more modern” LaunchDaemon.


sudo pico /Library/LaunchDaemons/com.mysql.mysqld.plist

Paste the following into that new file and save it.


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>KeepAlive</key>
    <true />
    <key>Label</key>
    <string>com.mysql.mysqld</string>
    <key>Program</key>
    <string>/usr/local/mysql/bin/mysqld_safe</string>
    <key>RunAtLoad</key>
    <true />
    <key>UserName</key>
    <string>mysql</string>
    <key>WorkingDirectory</key>
    <string>/usr/local/mysql</string>
</dict>
</plist>

All LaunchDaemons and LaunchAgents need to be owned by root.


sudo chown root /Library/LaunchDaemons/com.mysql.mysqld.plist

You will probably also want to add MySQL to your PATH if it isn't already there.


pico ~/.bash_profile

Copy and paste the following.


export PATH="/usr/local/bin:/usr/local/sbin:/usr/local/mysql/bin:$PATH" Alternatively, you may prefer to have Apache in your PATH as well.
export PATH="/usr/local/bin:/usr/local/sbin:/apache2/bin:/usr/local/mysql/bin:$PATH"

Reload your new profile. Make sure you get that leading dot.


. ~/.bash_profile

We will leave the MySQL configuration and copying of your old data up to you, but if this version of MySQL is newer than your last you should run mysql_upgrade.


sudo /usr/local/mysql/bin/mysql_upgrade --verbose --user=root --password=[password]

You may also want to update the MySQL Time Zone tables. You may incur some errors during the Time Zone table upgrade, but chances are that you can safely ignore them. If you can’t then you probably know what to do to fix them.


/usr/local/mysql/bin/mysql_tzinfo_to_sql /usr/share/zoneinfo | \
/usr/local/mysql/bin/mysql -u root -p mysql

Feedback or Questions?

If you have any feedback or questions go ahead and email them to phponsnowleopard at teamonetickets dot com and we will try to help you out.