Installing PHP 5.2 for Oracle on Mac OS X 10.5 (Leopard)

by Tony Bibbs

How to get your Mac set-up to build Oracle-based PHP applications

Published February 2009

If you've ever attended a PHP conference, you might have thought that Apple was a sponsor based on all the Mac laptops you saw. Many of the PHP developers toting Macs are running Linux as a virtual machine but more and more PHP developers work natively on the Mac. Recognizing this fact, Oracle has made it downright easy to develop PHP/Oracle applications on the Mac. In this guide I'll show just how easy it is to get your Mac setup to build Oracle-based PHP applications.


Before we get too far along it is important for you have a few things so you can follow along:

  • An Intel-based Apple computer with Mac OS X 10.5.x
  • Access to a server already running an Oracle database instance. For this demonstration, we'll use Oracle Database 10g Express Edition (XE) running on a Kubuntu instance from a Parallels virtual machine. Sorry, but Oracle Database XE will not run natively on your Mac.
  • Xcode 3.1 - Xcode, among other things, includes a C compiler used to build PHP. It's free for Apple Developer Connection members.
  • Fink or MacPorts (optional) - Provides development libraries that may be required depending on the features you need for your PHP build.
  • Familiarity with Terminal and running commands

Preparing Apache

If you are new to Macs, then one thing you probably noticed right away is how Linux-like a Mac can be. However, there are some one-off type things you will run into as compared to a Linux installation of PHP—the first example being the preparation of Apache.

With OS X 10.5, Apple began shipping 64-bit versions of Apache. This alone isn't a problem; however, my experience with some of the common PHP features like GD was nothing short of painful. Why? Well, it turns out that Fink and MacPorts make it hard to explicitly choose 64-bit versions of their libraries, which can eventually lead to a bunch of incompatibilities. You could try downgrading the stock Apache installation to 32-bit mode, but instead I would recommend compiling Apache from source.

  1. First download the source and uncompress it (we'll assume you put it in /path/to/httpd). Now configure Apache:
    #> cd /path/to/httpd
    #>./configure -enable-layout=Darwin -enable-mods-shared=all

  2. Finally build Apache:
    #> make 
    #> make install

Installing Oracle Instant Client

Before we can build PHP we must first install the Oracle Instant Client, which provides the required Oracle hooks that allow PHP and Oracle to talk to one another. There are two parts to the Oracle Instant Client: Basic (the plain-vanilla OCI client) and SDK (a development kit that includes the development headers needed to build Oracle support into PHP). Both can be downloaded from OTN.

It is important to install both parts to the same directory but the location of this directory is irrelevant. For the purposes of this guide let's assume you download them to /opt/oracle:

  1. Download the Basic client for OS X to /opt/oracle. It should be named something like "" where "X.Y.Z" is the current version of the client.
  2. Download the SDK to /opt/oracle. It should be named something like "" where "X.Y.Z" is the current version of the SDK
  3. .
  4. Unzip the basic client.
  5. Unzip the SDK.
Once done confirm you've properly unpacked both:

#> ls /opt/oracle/instantclient_10_2/ 

Verify the output from the above includes an sdk/ directory and a few .dylib files.

One last thing: because you are using the .zip versions you will need to manually create a couple of symbolic links:

#> mkdir -p /scratch/plebld/208/rdbms
#> ln -s /opt/oracle/instantclient_10_2/ /scratch/plebld/208/rdbms/lib
#> ln -s /opt/oracle/instantclient_10_2/libclntsh.dylib.10.1 /opt/oracle/instantclient_10_2/libclntsh.dylib 

The above is required for two reasons: first, during our PHP build, it will look for the OCI client in the default directory, which is scratch/plebld/208/rdbms/lib/. In theory there should be a way to override the default but as far as I know there is no easy way to do so without hacking up the makefile because PHP will look for the dynamically linked shared library libclntsh.dylib. Second, PHP will always look for the dynamically linked shared library libclntsh.dylib to ease upgrade compatibility.

Building PHP

( Note: A word on the stock Apache. Before publishing this guide I tried as best as I could to simply downgrade the stock Apache installation to 32-bit mode to avoid having to download, configure, and install it. Makes sense in practice but the reality is, this configuration gave me nothing but fits, probably because of how the stock Apache is built: the environment variables the Oracle Instant Client requires were simply not being passed to Apache yet everything worked just fine using the PHP command line interface. I tried in vain to pass those environment variables to Apache using a number of methods but it never worked so I opted to install Apache from source. )

Configuring PHP

To this point compiling PHP will seem quite familiar to those who know the typical "configure, make, make install" process. First configure PHP:

#> ./configure --with-apxs2 -enable-cli -with-

Now before you can actually do the build you'll need to edit the makefile generated to properly set a few things. First do a back up of the makefile you just generated:

#> cp Makefile Makefile.backup 

Now add some options to the CFLAGS_CLEAN compile option to an updated copy that you'll store in Makefile1.tmp.

#> cat Makefile | sed 's/CFLAGS_CLEAN = /CFLAGS_CLEAN = 
-I\/usr\/include -arch i386 -isysroot
\/Developer\/SDKs\/MacOSX10.5.sdk \#CFLAGS_CLEAN = /' > 

Similarly add some options to the EXTRA_LDFLAGS compile option to another updated copy stored in Makefile2.tmp.

#> cat Makefile1.tmp | sed 's/EXTRA_LDFLAGS = 
/EXTRA_LDFLAGS = -arch i386 -isysroot 
\/Developer\/SDKs\/MacOSX10.5.sdk -Wl,-
\#EXTRA_LDFLAGS = /' > Makefile2.tmp 

Get rid of leftover files:

#> rm Makefile Makefile1.tmp 

Now put your updated makefile back in place:

#> mv Makefile2.tmp Makefile 

Compiling PHP

Now you are ready to do the build:


Assuming no errors you can safely do the installation.

#>make install 

Post installation (Apache Environment Variables)

Ok, almost done. The last thing you need to do is ensure that DYLD_LIBRARY_PATH is set. To do this edit /private/etc/apache2/httpd.conf and add the following to the top of that file:

SetEnv DYLD_LIBRARY_PATH /opt/oracle/instantclient_10_2 

When you have those set be sure to restart Apache:

#> apachectl stop 
#> apachectl start 

Verifying the Build

Now that the build is done you should verify everything went as expected. To do that, create a PHP file (e.g. info.php) in your Web server's document root with the following code:

<?php phpinfo(); ?> 

Now view the phpinfo() output in your browser and ensure that:

  • The "Configure Command" includes the -with-oci8 option you gave it
  • The "OCI8" section exists and shows it is enabled
  • The "Apache Environment" section shows the DYLIB_LIBRARY_PATH variable pointing to the location of your instant client location (i.e. /opt/oracle/instantclient_10_2)

Setting up Parallels

Before you can do a final test of your Mac/OCI8 installation you need to set up a server running an instance of Oracle Database XE. (We'll assume you already have Parallels installed.)

Launch Parallels Desktop. When prompted for which virtual machine to run, select New:


Then select Custom for the operating system:


Then select Linux as the OS Type and Other Linux Kernel 2.6 as the OS Version:


Because Oracle is a world-class DBMS, you'll want to be sure to give it plenty of RAM. Failing to do so will prevent the Oracle installation from working. I gave this new virtual machine 2048MB:


Then create a new hard disk image:


For networking I selected Host-only networking, which means our new virtual machine can see the Mac and other Parallels-based virtual machines but they won't be exposed to your corporate network or internet:


Then pick a sane name for your virtual machine. In this case we are running Kubuntu:


You'll then want to optimize your virtual machine like so:


After that it's a matter of inserting the Kubuntu CD and running its installer. When you are done you will want to use The Underground PHP and Oracle Manual to get Oracle Database XE installed and working.

Testing Oracle Database XE Connectivity from PHP

To confirm our build is working completely let's build a simple script that connects to the sample user HR that is included with Oracle Database XE. Before you can do this you will need to unlock the HR account and set a password using Oracle Application Express or SQL*Plus. (See The Underground PHP and Oracle Manual for how to do this.) Once you've enabled the HR user, connect as follows being sure to replace the settings to reflect your installation:

// Make a connection
$c = oci_connect('hr', 'myhrpassword', '//myoraclehost/XE');
// Echo out what should be an Oracle resource

Congratulations, you have just installed PHP for use with Oracle Database XE on Mac OS X. 

Further Reading

Tony Bibbs is an active participant in the PHP and open source communities and currently works for the State of Iowa; has been a vocal advocate for the use of open source software in government. Tony is also the owner and software architect for Apteno L.C. based in Urbandale, Iowa as well as co-founder of Two Lane Technology, a transportation logistic company.