Enabling Oracle OCI8 PHP Extension on OS X Snow Leopard

My current project involves using PHP with an Oracle database. Oracle apparently embraces PHP warmly and as such supports an open source database driver for the environment called OCI8. As a Mac user I was looking to use OS X's built-in Apache and PHP setup, which like many PHP installations does not have the Oracle OCI8 driver installed or enabled. It took me some time and research to get it up and running. I was using Oracle Express, a limited capability, free-ish version of Oracle's database. Oracle Express was installed on a separate Windows machine as it cannot run or be installed on Snow Leopard. I also assume that you enabled PHP in your Apache configuration (/etc/apache2/httpd.conf) and have a /etc/php.ini by copying it from /etc/php.ini.default.

OCI8 relies on OS X having several client libraries and tools from Oracle installed on OS X. For most intents and purposes download the 64-bit version of the following files under the title "Version (64-bit)": 

Registration is required for all downloads.

Once downloaded, unzip all three files, which will look like this on your file system

Now, create a separate directory (which I called instantclient_10_2) and copy the contents of all the files included in these subfolders into it, which will look something like this:

The next step is to copy the necessary files into your OS X dynamic library and bin directories (as described here). Open a terminal window and go to the directory above the one you created containing all the files you unzipped.

sudo cp instantclient_10_2/sdk/include/*.h /usr/include

sudo cp instantclient_10_2/sqlplus /usr/bin

sudo cp instantclient_10_2/*.dylib /usr/lib

sudo cp instantclient_10_2/*.dylib.* /usr/lib

Now move to the /usr/lib directory and create the following link:

sudo ln -s libclntsh.dylib.10.1 libclntsh.dylib

To test, open another terminal window or tab, and try to run Oracle's SQL*Plus tool using
/usr/bin/sqlplus. If it worked, you are almost there. Exit SQL*Plus by entering quit or simply Ctrl+C.

You now have the Oracle tools installed. Now, to install OCI8, which we will install from the PECL repository. In a terminal window enter

sudo pecl install oci8

[If you see an error here, you may not have Pecl or Pear (PHP package managers) installed. In that case look at these installation instructions]

OCI8 will download and will eventually give you the prompt:

Please provide the path to the ORACLE_HOME directory. Use 'instantclient,/path/to/instant/client/lib' if you're compiling with Oracle Instant Client [autodetect] :

In response enter:


We are doing this because Oracle is not installed on our local machine. If it were we would respond with the path to Oracle's installation directory. Once entered, PECL will compile and build OCI8. Once done, it will ask you to enable the extension in your PHP configuration. To do that, open php.ini and add the line (normally among the list of extensions):


Once done, you can start Apache again using

sudo apachectl start

To test the installation, enable the HR account in your Oracle installation and run a PHP file such as (make sure you replace the password and database server IP or name in the code):


< ?php
$c = oci_connect(&#39;hr&#39;, <password here="">, &#39;<server ip="" name="" or="">/XE&#39;);
$s = oci_parse($c, &#39;select city, postal_code from locations&#39;);
print &#39;&#39;;
while ($row = oci_fetch_array($s, OCI_NUM+OCI_RETURN_NULLS)) {
print &#39;&#39;;
foreach ($row as $item)
print &#39;&#39;;
print &#39;&#39;;
print &#39;
<table border="&quot;1&quot;">

Tags: , , , , , , , , , , , , , , , ,


  1. Really nice programming talents you could have there. i am a programmer myself however I still need to be told till I succeed in your ability. nice write-up!

  2. Thanks for the great tutorial.  I completed the process (with some additions, noted below), but when I try to test the connection, PHP says:
    dyld: lazy symbol binding failed: Symbol not found: _OCIEnvNlsCreate
      Referenced from: /usr/lib/php/extensions/no-debug-non-zts-20090626/oci8.so
      Expected in: flat namespace

    Any ideas?  I Googled that error without much luck.

    I am on Mac OS X 10.7 Lion, so I needed to install PEAR/PECL, using the instructions here:


    I also ended up installing XCode from Apple:


    in order to get PECL to install the OCI8 extension… I was getting a “cannot find autoconf” error from PECL.

    In the first installation step, I also needed to sudo mkdir /usr/include.

  3. Let me look into this.
    I did perform this on Snow Leopard.

  4. Thanks!  I'm kind of banging my head against the wall; not sure if it has something to do with the PATH variable or what might be going on.

  5. According to a post on the Oracle discussion board (https://forums.oracle.com/forums/thread.jspa?threadID=2256568) it appears that support for Lion is fairly non-existent.

    I tried following my own directions on Lion and ended up getting a segmentation fault error when trying to run SqlPlus. Not a very good outcome. I wish I could help more.

  6. Well that's a bummer but I sure appreciate you taking a look.  I rooted around a little more and came to more or less the same conclusion; it's a no-go with Lion.

  7. Did anyone get anymore information regarding the installation on Lion?
    Is there any other alternative to this?

  8. kt,

    Apparently some folks tried and successfully installed the 32-bit OS X client on Lion and it does seem to work. Look at https://forums.oracle.com/forums/thread.jspa?threadID=2187558&start=15&tstart=0

    I will verify and update my post to reflect it if I am successful.


  9. Thanks Yuval.
    I tried installing it this is the error I got
    ERROR: `/private/tmp/pear/temp/oci8/configure –with-oci8=instantclient,/usr/lib' failed

  10. KT,

    I followed the link recommendation on Lion and ‘installed’ the 32-bit version of the driver. While I seemed to be able to get Oracle’s SQLPlus to work (no segmentation faults), oci8 had problems linking dynamically with PHP. Testing oci8 with the command line
    php –ri oci8
    Shows that error.

    I suspect that the cause of the issue has to do with the 32-bit/64-bit compilations that prevent the 64-bit PHP to work with a 32-bit driver. It may be total bull but at this moment, it is where I am stuck with this.

    Sorry I could not give you a solution.

  11. kt,

    I tried what was recommended in the link I posted and ‘installed’ Oracle’s 32-bit version of SQLPlus and Instant Client. While they did work and I was apparently able to use SQLPlus to connect to a server without a segmentation fault, I did not have that much luck with PHP and oci8. From the error I saw when I ran the PHP command line
    php –ri oci8
    which shows extension configuration, there were errors with dynamic library linking. That looks to me (and I may be wrong) as issues having to do with the 64-bit nature of compiling oci8 or PHP itself and the 32-bit nature of the Oracle tools.
    Maybe someone who reads this may have more success and will be able to connect these last two dots.

  12. kt,

    I followed the directions for the link and using the path outlined in my post 'installed' the 32-bit Oracle Instant Client and SQLPlus on my OS X Lion machine. It did appear like SQLPlus was able to connect to a remote machine.

    It did not seem like I fared as well with oci8 and PHP.

    Using PECL I downloaded and installed the oci8 extension, but it did not appear to show up in phpinfo() as enabled. Additional observation using the command line

    php –ri oci8

    showed that PHP was having issues loading the dynamic library that was compiled for oci8 when PECL installed it. 

    My guess is that oci8 and PECL may have been installed with 64-bit-complied code while the Oracle pieces used 32-bit code and libraries. 

    Maybe someone who reads this post and thread will have better luck than us making it all work on Lion…

  13. Thank you so much Yuval. I also found out that its the oci8 module that has some problems

  14. Hi Yuval
    I managed to get the installation completed..But it says that the php.ini file cannot be found.
    php.ini "/private/etc/php.ini" does not exist
    I am using the default php.ini.default file. Do you know of any way to solve this?

  15. The one thing that comes straight to my mind with your question is to check whether you actually have php.ini in your /etc directory.

    OS X comes with a 'standard' file for PHP called


    which you are supposed to save as php.ini once you configured and approved all options.

    You can look and see where the file you are looking for is by running

    php --ini

  16. If I change the file to php.ini the php page doesn't show up. I get a blank phpinfo page

  17. That normally means that there is an error somewhere in the Apache configuration. Is PHP enabled in /etc/apache2/httpd.conf ?

    Also look at


    To see if no errors were reported by either Apache or PHP

  18. kt,
    PECL does complete the OCI8 extension installation but as yuval points out, you get an error when running php –ri oci8. Are you saying you don't get that error and that you can connect to databases in PHP using OCI8? If so, how did you manage to do that? I'm also having the same problem.

  19. Here's the error I get after PECL installs OCI8:
    $ php –ri oci8
    OCI8 Support => enabled

    Version => 1.4.7
    Revision => $Revision: 321634 $
    Active Persistent Connections => 0
    Active Connections => 0
    dyld: lazy symbol binding failed: Symbol not found: _OCIClientVersion
      Referenced from: /path/to/lib/php/extensions/no-debug-non-zts-20090626/oci8.so
      Expected in: flat namespace
    dyld: Symbol not found: _OCIClientVersion
      Referenced from: /path/to/lib/php/extensions/no-debug-non-zts-20090626/oci8.so
      Expected in: flat namespace
    Trace/BPT trap: 5

  20. I've installed the 32 bit client and that works OK to connect to Oracle via SQLPLUS.  But trying to compile OCI using "sudo pecl install oci8" I get this weird error: "configure: error: invalid value of canonical build".   I used "-" versions of Instant Client, SQLPLUS and SDK, on OS X Lion Server 10.7.4.  Any suggestions?

  21. I am afraid that is where I too got stuck. It appears that OCI’s own compilation does not seem to work with the 32-bit client. Very frustrating.

  22. Brice Miramont

    it does work if you choose the 64bit version of the Instant client version 
    Juste change the sudo ln -s libclntsh.dylib.10.1 libclntsh.dylib 
    to sudo ln -s libclntsh.dylib.11.1 libclntsh.dylib
    and it works on my macbook air running 10.8.2

  23. Brice Miramont

    Sorry, forgot the Version : (64-bit) 
    from the Oracle Instant client download page (Mac)

    it is indeed a 32-bit/64-bit problem. You need to install oci8 manually.
    From a Terminal running as an admin user with autoconf installed.
    cd /tmp
    pecl download oci8
    tar –xvzf  oci8-x.x.x.tgz
    cd oci8x.x.x.x
     Run phpize from your webserver install e.g /usr/bin

     Set the correct binary flag option for 32-bit compile:

     export CFLAGS=”-m32”
    Configure oci8:
     ./configure –with-oci8=shared,instantclient,/Users/mike/instantclient11_2
    make clean 
    make install
    extension=oci8.so to php.ini
    stop and start webserver

  25. I installed the 64 bits client Oracle instantclient-sqlplus-macos.x64- and other related files.
    SQLplus works.
    I also installed oci8 extension using PECL. It is at /usr/lib/php/extensions/no-debug-non-zts-20090626/oci8.so
    I made the necessary changes in php.ini inserting the line 
    As pointed out by John, same error message "dyld: Symbol not found: _OCIClientVersion"
    $ php –ri oci8

    OCI8 Support => enabled
    Version => 1.4.9
    Revision => $Id: e2241cffb72c940cb2ca267b7a6a0ce436de7e5e $
    Active Persistent Connections => 0
    Active Connections => 0
    dyld: lazy symbol binding failed: Symbol not found: _OCIClientVersion
      Referenced from: /usr/lib/php/extensions/no-debug-non-zts-20090626/oci8.so
      Expected in: flat namespace
    dyld: Symbol not found: _OCIClientVersion
      Referenced from: /usr/lib/php/extensions/no-debug-non-zts-20090626/oci8.so
      Expected in: flat namespace
    Trace/BPT trap: 5

    Any new ideas one year later ?
    Thanks a lot.

  26. It appears I had the old libclntsh.dylib.10.1 still installed in /usr/lib and the symbolic link pointed to this old library. Removing libclntsh.dylib.10.1 and with the correct symbolic link sudo ln -s libclntsh.dylib.11.1 libclntsh.dylib OCI8 if finally installed. Confirmed with php –ri oci8 and phpinfo() after apache restart. (Mountain Lion 10.8.3 ; 64 bits Oracle instantclient packages)     Thank you for your tutorial !

  27. Antonio Martinez

    I’m not going to do it, but I could kiss you for this step-by-step guide. Thanks so much.

    I ran into some variations, like the symlink version number, and I did have MAMP so I had to download / untar / .configure from sources, but I finally got my oci8. Now it’s time to (try to) use it and “enjoy”.

    Thanks again. +100 karma points.

  28. Agree 100% with Antonio. This guide was helpful beyond words. Every other source I found (especially the Oracle “documentation”) is impossible to decipher. Thank you!

  29. Thanks!.
    Anyone knows how to setup TNS after this tutorial?

  30. Mike’s solutions should work, run make clean before make if you tried diferent instantclient versions

  31. We put a man on the moon but it’s still this hard to get oracle to play nice with php?

    Regardless, you are a gentleman and a scholar. Thanks, saved me so much time.

Leave a Reply

Your email address will not be published. Required fields are marked *