Upgrading the Native PHP Installation on OS X Mountain Lion

Let’s see how we can manually upgrade the native OS X 10.8 PHP installation to the newest version (currently 5.4.5) and get some other useful software installed while we’re at it. *AMP packages are practical, but rarely up-to-date, so absorbing the procedure depicted in this article is invaluable to every PHP developer.

The Theory of Building From Source

If you’re only interested in the practical aspect of installing PHP, feel free to skip this section, but it might be useful for you later on to know how it actually works and why certain commands are necessary.

Every installation of software from source follows basically the same chain of commands: Download the source files, configure, make, optionally test, install.

Configure

The “configure” script tells “make” what’s going to be built. Executed by typing “./configure”, the configure script analyzes dependencies, verifies you’re running a supported OS, sets up the necessary files for the given OS and finally generates a makefile, which when “make” is called, dictates how and what exactly is to be built.

“configure” tells “make” what’s going to be built

If the configure script finds missing dependencies or errors, it performs an exit and stops execution, allowing the user to remove or work around any obstacles before proceeding. The configure command always comes first when building from source.

Make

Next, “make” builds what configure told it to build. “make” is initialized by simply typing “make”, and is actually a GNU utility which is generally used to maintain a set of files and recompile them if necessary.

“make” builds what configure told it to build

To function, it requires a makefile – a file in which its directives are described and relationships between the files in question are noted. Once run, the make command reads the makefile and performs the tasks.

The “make test” command runs the make command but also tests the compilation against a test target. Not all source distributions support “make test”, so unless explicitly specified in the installation documentation of the software being installed, one is to use the regular “make”.

The “make test” command runs the make command but also tests the compilation against a test target.

“sudo make install” installs the files that “make” built into predefined folders. It handles all inclusions, updates and resolves paths and moves everything to where it should be. Effectively, it finishes the installation and the user typically doesn’t need to do anything else.

This is actually exactly what Homebrew – the package manager we install in the next section – can do. It can execute the same flow, internally. You don’t really see any of it directly, but more or less the same chain is executed, if the “formula” submitted by the “brewer” is made that way.

It makes the entire process less cumbersome by automatically checking for dependencies and installing them before moving onto the main designated package. It then downloads and unarchives it and executes the configure, make, make install chain to finish up the installation.

Almost every installation from source follows the same steps: download, configure, make, install.

Homebrew

From Homebrew home

In order for the installation of PHP to go as smoothly as possible, we need to install Homebrew, a package manager for OSX which can handle a lot of installations for you – installations that might otherwise require complex build procedures and can have critical dependencies which take hours to resolve.

Having Homebrew installed will benefit you in the long run.

Having Homebrew installed will benefit you in the long run, not just for the purpose of this article. It offers a quick way to install common libraries and software without having to build from source.
To install it, we need to do the following (skip this section if you have Homebrew installed):

1. Install XCode via the App store. Once installed, install Command Line Tools through the XCode app itself, or download and install from http://developers.apple.com. We need XCode and CLT because Homebrew requires them.
2. Install X11 from here. This is also a Homebrew requirement. Pick the latest version available, not necessarily the one linked here.
3. Install Homebrew from GitHub.
4. If you run into problems, you might have to do the following after step 1 and 2:

   $ sudo xcode-select -switch /Applications/Xcode.app/Contents/Developer
   $ ln -s /opt/X11 /usr/X11
   

   ..taken from this post. This happens on some instances of Mountain Lion for some reason.

Once done, run brew doctor and verify that everything works (as per instructions on Homebrew’s website).

PHP

Predictably, installing PHP requires you to have certain libraries installed. Luckily, Homebrew is here to handle these installations for us. Install the following:

brew install libjpeg
brew install pcre
brew install libxml2
brew install mcrypt

Once done, download the PHP source files from Php.net. Unpack the archive, open your terminal, and switch to the source folder (e.g. cd ~/Downloads/php-5.4.5/ or wherever else you downloaded the sources).

If you’re planning to work with Zend Framework 2 and want to start with the sample skeleton application as made by Rob “Akrabat” Allen, or if you intend to deploy your application in multiple langauges, you need php-intl support. To allow the configure script to take php-intl into consideration while building the makefile, we need to install another dependency – ICU. Download this from ICU-Project.org and execute:

tar xzvf icu4c-4_8_1-src.tgz
cd icu/source
./runConfigureICU MacOSX
make
sudo make install

This handled all the basic dependencies PHP could ever want from us (for now). We can now finally build and install it.

Installing

First, while in PHP’s unarchived source folder, execute the following configure command:

./configure  \
--prefix=/usr  \
--mandir=/usr/share/man  \
--infodir=/usr/share/info  \
--sysconfdir=/private/etc  \
--with-apxs2=/usr/sbin/apxs  \
--enable-cli  \
--with-config-file-path=/etc  \
--with-libxml-dir=/usr  \
--with-openssl=/usr  \
--with-kerberos=/usr  \
--with-zlib=/usr  \
--enable-bcmath  \
--with-bz2=/usr  \
--enable-calendar  \
--with-curl=/usr  \
--enable-dba  \
--enable-exif  \
--enable-ftp  \
--with-gd  \
--enable-gd-native-ttf  \
--with-icu-dir=/usr  \
--with-iodbc=/usr  \
--with-ldap=/usr  \
--with-ldap-sasl=/usr  \
--with-libedit=/usr  \
--enable-mbstring  \
--enable-mbregex  \
--with-mysql=mysqlnd  \
--with-mysqli=mysqlnd  \
--without-pear  \
--with-pdo-mysql=mysqlnd  \
--with-mysql-sock=/var/mysql/mysql.sock  \
--with-readline=/usr  \
--enable-shmop  \
--with-snmp=/usr  \
--enable-soap  \
--enable-sockets  \
--enable-sysvmsg  \
--enable-sysvsem  \
--enable-sysvshm  \
--with-tidy  \
--enable-wddx  \
--with-xmlrpc  \
--with-iconv-dir=/usr  \
--with-xsl=/usr  \
--enable-zip  \
--with-imap=/usr/local/imap-2007 \
--with-kerberos \
--with-imap-ssl \
--enable-intl \
--with-pcre-regex  \
--with-pgsql=/usr  \
--with-pdo-pgsql=/usr \
--with-freetype-dir=/usr/X11 \
--with-jpeg-dir=/usr  \
--with-png-dir=/usr/X11

Once done, execute

$ make test

”make test” runs make and tests the compilations for errors

As mentioned in the section on Build Theory, this runs make and tests the compilation. This might take a while, up to 30 minutes, because every single facet of PHP is being tested. When finished, if PHP found any errors (and it probably will) report them to the developers by following the on-screen instructions. Don’t worry, everything is still fine – the errors it finds are usually less than important.

As you can see, some 11503 tests are to be performed. This will take a while.

If you have the original PHP already activated and configured, make a backup of your php.ini file now. It should be in /etc/php.ini

Finally, run the following to actually install PHP.

$ sudo make install

It is best not to overwrite the new php.ini file with your old one if you made a backup. Instead, copy the values you need manually, to stay on the safe side – that way we make sure the new php.ini file is fully compatible with the newly installed version.

Apache configuration

Almost finished! If you had already activated PHP on your machine before this and the only purpose of reading this article was actually upgrading the existing PHP, then you’re done – everything should work.

If not, however, we need to enable PHP in OSX’s native Apache installation. Since the httpd.conf file will probably be in the default location, open it via Terminal in TextEdit like so:

$ SUDO_EDITOR="open -FWne" sudo -e /etc/apache2/httpd.conf

I am using the SUDO EDITOR command here in order to open the file in TextEdit, simply because I deem it much easier to edit files in than Vim or Nano. I could just as well have used “$ sudo vim /ect/apache2/httpd.conf” to edit it in vim.

Next, Uncomment the following lines (they are not next to each other – use the Find command to locate them)

LoadModule php5_module        libexec/apache2/libphp5.so
Include /private/etc/apache2/extra/httpd-vhosts.conf

The first line activates the use of PHP as an Apache module. The second line is there so that the main httpd.conf (Apache’s configuration) file harvests the virtual hosts from the vhosts file and saves us the trouble of excessive editing in the overly sensitive httpd.conf. This has the additional benefit of letting you save a vhosts file somewhere outside /etc, and backing it up for other development machines or reinstallations.

A very practical approach to this is hosting it on a cloud service like Google Drive or Dropbox and linking to it directly from httpd.conf. That way, when you add a new virtual host, it is automatically installed on every one of your machines just as soon as you restart the local Apache server.

Adding a Vhost and Wrapping Up

A virtual host is a locally hosted imaginary domain. It basically lets you test out your projects in the browser by entering different URLs. For example, on my machine, I could visit http://mactuts.tutorial and see the Hello World app this sections ends with, or I could visit http://mw.dev to see the development version of a project I’m working on. Quite simply, a different URL triggers a different source folder and opens a different project as a website. Here’s a quick guide on how to add a vhost – if you have vhosts set up already or understand everything about them, feel free to skip this section.

Step 1: Editing the hosts file

First, we’ll name our sample vhost “mactuts.tutorial”. To do this, add an entry into /etc/hosts that looks like this:

127.0.0.1        mactuts.tutorial

This means accessing the url http://mactuts.tutorial in the browser will go to 127.0.0.1:80 or, in other words, to port 80 of our local server (Apache).

This is an example hosts file. Notice I also have some other virtual hosts set up on this machine

Step 2: Add an Apache vhost

Next, add a block into etc/apache2/extra/httpd-vhosts.conf that looks something like this:

<VirtualHost *:80>
    ServerName mactuts.tutorial
    DocumentRoot "/Users/{USERNAME}/Sites/mactuts"
    ServerAdmin bruno@skvorc.me
        <Directory "/Users/{USERNAME}/Sites/mactuts">
            Options Indexes FollowSymLinks
            AllowOverride All
            Order allow,deny
            Allow from all
        </Directory>
</VirtualHost>

Replace {USERNAME} with your own username, without the curly braces. This tells Apache the following: If you have something on port 80, check its original url name. If it’s mactuts.tutorial, then set up all those options.

Step 3: Restart Apache

Next, restart Apache with

$ sudo apachectl restart

Step 4: Create the Index File

3) Create a the folder “/Users/{USERNAME}/Sites/mactuts” (naturally, replace {USERNAME} with your OSX user’s name) and place an index.php file into it with the following content:

<?php echo 'Hello world'; ?>

Step 5: Check it out!

Go to http://mactuts.tutorial. You should see “Hello World”!

Alternatives

Recently, an alternative to this approach popped up – installing PHP through Homebrew itself. The problem is, there are no official channels at the time of this writing (early August 2012) so an alternative tap needs to be activated for Homebrew.

Also, the OS X version I tested this on, Mountain Lion, unfortunately failed to install that way and threw vague errors at me which I could not resolve. If you feel adventurous check this post out and try to modify it according to your own OS and desired PHP version.

A more stable alternative seems to be available here, but the feedback is lax and there’s not much to go on, so I’ll leave these methods up to the experimentation of the readers.

Updates

Here are a few alternatives suggested by commenters since the post was published.

php_osx
Another (seemingly smooth-working) alternative to this was brought to my attention by commenter DaftViking and includes installing PHP via php_osx.

Macports
Although I encourage the phasing out of Macports in favour of Homebrew, it seems Macports added a stabilized version of PHP as well, so it might provide another working alternative. I have personally not tested this approach, but for those proficient with Macports, further information can be found here. Thanks to Redditor nemeth88 for the heads up!

Conclusion

OS X comes with a preinstalled PHP and Apache configuration. Sadly, the PHP version that it comes with is severely outdated, and it never updates except when a new OS version is being installed. By then, the new PHP version included is already out of date, so besides fetching an *AMP (Apache/Mysql/Php) package (which rarely, if ever, has up-to-date versions of PHP), what can one do except update it manually?

In this tutorial we’ve covered the basics of building from source, we’ve built a new up-to-date version of PHP and installed it, and we’ve even installed Homebrew which will make further installations of software and libraries super easy. We also covered the creation of a virtual host and tested our installation to make sure it works. I hope you’ve enjoyed it and that everything worked as planned. If you run into problems, feel free to post in the comments and we’ll work through the issues together.