baldwhiteguy.co.nz

Technical Blog

Enable Oracle OCI8 PHP Extension on Mac OS X

26-January-2015

26JanuaryThe last major step for getting an Oracle development environment functioning on my Mac Mini was the setup of the OCI8 connector needed to enable PHP connectivity through to my Oracle database. There are other methods such as the Zen Framework where all that stuff comes built-in … but I don’t necessarily want to be tied to that ongoing. I thought that OCI8 was be just a simple install - but it turned out to be the trickiest part. Typically, after several attempted installs, trying different variations, the solution to get things working was very simple … but missing one documented step. As such, these notes cover the final install method I used. Mostly they’re intended to help me in the event I ever need to repeat the process with a brand new Mac - but hopefully they might also help others attempting the same process.

Step 1: Pre-requisites

There are several pre-requisites for configuring OCI8:

Oracle Instant Client and the SDK - as per these install instructions.
Apple’s Xcode command-line tools (ideally v6.1 or above). This includes the gcc compiler, along with make tools needed for the installation of both Homebrew and OCI8. This used to involve a sizeable download of the full Xcode package from the Mac App Store, but Mavericks and Yosemite now allow the command line tools component to be installed separately as per these instructions.

After installation, you’ll need to open Xcode to accept the licence, or enter the terminal command:
sudo xcodebuild -license
Homebrew is an OS X package manager used for installing Unix tools and open source packages.
See these homebrew install instructions.
PEAR and PECL. These are both extension libraries for PHP. The latter is essential for compiling the Oracle OCI8 library (written in C). PEAR and PECL are bundled together so that it’s single install as per these instructions.

If PEAR and PECL are already installed, the following commands will update you to the latest version:
sudo pear channel-update pear.php.net
sudo pecl channel-update pecl.php.net
Autoconf. This is another tool used by open source projects to generate makefiles and dynamic libraries. The install process using homebrew is very easy. Just enter the following command:
brew install autoconf

Step 2. Compiling the OCI8 Libraries with PECL

There are two alternative methods for installing OCI8 via PECL. I tried both while attempting to get things properly configured on my system. Both methods do the same thing - except that method 2 allows you to choose an earlier oci8 version in the event that the current one seems not to be working.

Method 1
This first method is easiest, using PECL to automatically download and build the OCI8 extension. Although its a fairly involved process it’s all scripted and managed by PECL - and is initiated using the simple command.

sudo pecl install oci8

If you already have OCI8 installed but need to re-build then you’ll need to use the -f option to force a re-build:

sudo pecl install -f oci8

Once initiated, PECL displays the prompt below to get the location of your ORACLE_HOME (Instant Client) directory:

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 my case, the appropriate response was:

instantclient,/Library/Oracle/instantclient_11_2

A series of automated checks will flash past in your terminal screen as PECL checks your environment and prerequisites - then performs the build. In my case, a few minor warning messages were displays about items in the source code - but these looked safe to ignore and didn’t interfere with the build process.

Eventually, a success message should be displayed similar to that below:

Build process completed successfully
Installing '/usr/lib/php/extensions/no-debug-non-zts-20121212/oci8.so'
install ok: channel://pecl.php.net/oci8-2.0.8
configuration option "php_ini" is not set to php.ini location
You should add "extension=oci8.so" to php.ini

Method 2
This is a slightly more manual variation of method 1. However, it has the advantage of allowing you to choose specific OCI8 versions depending on the package file you download.

Download the oci8 PECL package from pecl.php.net/package/oci8

Untar the package, extracting it anywhere you like.

Open terminal. Go to the directory containing the extracted package, and execute the four command lines below. These essentially execute the run process as the pecl-managed install in method 1.

phpize
./configure --with-oci8=shared,instantclient,/path/to/instant/client/lib
make
sudo make install

Substitute /path/to/instant/client/lib with the path to your ORACLE_HOME (Instant client) directory as per Method 1 above.

Be aware that warnings may be displayed when executing the make command (as also occurred in method 1), BUT
the build should still complete successfully.

Step 3. Update PHP.INI

With the build complete, you need to update your php.ini file to ensure the new OCI8 extension is included in your configuration options. If you’re already using PHP then you’ll likely already have the php.ini - but if you’re not actively using/configuring PHP on your Mac then this may be new territory.

By default, OS X 10.10 Yosemite stores its PHP configuration files in /etc (or /private/etc). If you go to this directory you’ll see an existing configuration file called php.ini.default

If you don’t already have your own custom php.ini file, create this by copying the default version.

sudo cp php.ini.default php.ini

You can now edit this copy to include your own custom configuration settings:

sudo edit php.ini

Go to the Dynamic Extensions section of the php.ini file.
This starts at line 834 in my version of the file.

Add the line:

extension=oci8.so

This is the standard Unix (and Mac OS X) format for adding a PHP extension.
Save the updated file, then exit.

It may also prove useful to update the permissions on your php.ini file. In his PHP setup article, Rob Allen (see references below) recommends applying the following changes.

sudo chmod ug+w php.ini
sudo chgrp admin php.ini

If you haven’t yet configured PHP on your system, refer to the documentation on PHP.net for making use of OS X’s bundled PHP functionality.

Step 4. Edit Apache org.apache.httpd.plist file

This is the step missing from most other documentation for OCI8 installs. I’m not sure of the technical details - but after some Internet searching and experimentation I discovered that it was needed for PHP to recognise OCI8 on my system.

The org.apache.httpd.plist file needs updating to reference the DYLD_LIBRARY_PATH variable. The value should be set to the path of your Oracle Instant Client home.

This needs to be added into the <dict> section of the file
Because the file format is XML, you need to make TWO entries.
The variable name, DYLD_LIBRARY_PATH, must be enclosed between the <key></key> tags.
The variable value must be enclosed between the <string></string> tags.

To edit the file, open a terminal window and enter the following commands:

cd /System/Library/LaunchDaemons
sudo edit org.apache.httpd.plist

The change is illustrated in the image below.
Save the updated file and exit.

Restart Apache for the changes to take effect.

sudo apachectl restart

Step 5. Verify the OCI8 Configuration

With the configuration of OCI8 now complete, the final step is to verify that its working. The easiest way to do this is to open terminal and execute the command:

php -i

This is will display the global configuration settings for PHP, as well as the settings for each module. The output should include details for the OCI8 module similar to that shown below.

andrew$ php -i
phpinfo()
PHP Version => 5.5.14

System => Darwin Andrews-MacBook-Pro.local 14.1.0 Darwin Kernel Version 14.1.0: Mon Dec 22 23:10:38 PST 2014; root:xnu-2782.10.72~2/RELEASE_X86_64 x86_64
Build Date => Sep 9 2014 19:04:27
   ..
   ..
oci8

OCI8 Support => enabled
OCI8 DTrace Support => disabled
OCI8 Version => 2.0.8
Revision => $Id: f04114d4d67cffea4cdc2ed3b7f0229c2caa5016 $
Oracle Run-time Client Library Version => 11.2.0.4.0
Oracle Compile-time Instant Client Version => 11.2

Directive => Local Value => Master Value
oci8.connection_class => no value => no value
oci8.default_prefetch => 100 => 100
oci8.events => Off => Off
oci8.max_persistent => -1 => -1
oci8.old_oci_close_semantics => Off => Off
oci8.persistent_timeout => -1 => -1
oci8.ping_interval => 60 => 60
oci8.privileged_connect => Off => Off
oci8.statement_cache_size => 20 => 20
    ..
    ..

A better option is to create a php page in your apache web documents folder calling the phpinfo() function. When viewed in a browser, this will display the full configuration of your PHP install (including the OCI8 module if properly configured) in a much more readable format.

<?php
// Show all information, defaults to INFO_ALL
phpinfo();
?>

The output, viewed in a browser, should look similar to that below:

Confirm OCI8 configuration via phpinfo()

If you have an Oracle database available, you can further verify the installation using a simple PHP script that connects to a database and calls the Oracle sysdate function as below. Make sure to change the database login and other connectivity details to match your system.

<?php
   //File: dbtime.php
    $dbHost = "l92.168.0.100";
    $dbHostPort="1521";
    $dbServiceName = "orcl";
    $usr = "hr";
    $pswd = "hr";
    $dbConnStr = "(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=".$dbHost.")(PORT=".$dbHostPort."))
     (CONNECT_DATA=(SERVICE_NAME=".$dbServiceName.")))";
    if(!$dbConn = oci_connect($usr,$pswd,$dbConnStr)) {
       $err = oci_error();
       trigger_error('Could not establish a connection: ' . $err['message'], E_USER_ERROR);
    };
    $strSQL = "SELECT TO_CHAR(SYSDATE, 'HH:MI:SS') ctime FROM DUAL";
    $stmt = oci_parse($dbConn,$strSQL);
    if (!oci_execute($stmt)) {
       $err = oci_error($stmt);
       trigger_error('Failed to execute the query: ' . $err['message'], E_USER_ERROR);
    };
    oci_fetch($stmt);
    $rslt = oci_result($stmt, 'CTIME');
    print "<h3>The current time is ".$rslt."<h3>";
?>

Using the dbtime.php script to verify OCI8 connectivity

References

Rob Allen - Setting up PHP & MySQL on OS X Yosemite. Although targeted at a different database, and not including OCI8, this article provides a good summary of the required PHP and Apache configuration.

PHP.net - Using the Mac OS X bundled PHP. More detail info about configuration required to use the bundled PHP (and Apache) version on your Mac.

Enavigo - Enabling Oracle OCI8 PHP Extension on OS X Snow Leopard. Although out of date, it provides a good overview.

Deptz - How To Enable OCI8 on PHP 5.4 and Install Oracle Instant Client on Mac OS X 10.9 Mavericks. Another good article that helped me figure things out … including the missing step to update the httpd.plist file.

PHP.net - Oracle OCI8 Manual. Official reference guide for PHP and OCI8.

Christopher Jones and Alison Holloway - The Underground PHP and Oracle Manual. Another useful reference guide to anyone beginning PHP development with Oracle.

Footnote: Reinstalling Older Module Versions via PECL

In my notes for the installing the OCI8 module, I stated that a manual download from pecl.php.net/package/oci8, then calling the phpize and ./configure commands (see Step 2 above), was the only way to install an older version if you needed to.

However, I’ve subsequently discovered that PECL will let you do this too. You just need to explicitly append the version number onto the module name. For example:

To install version 2.0.7 of OCI8, enter the command line:

sudo pecl install -f oci8-2.0.7

Andrew Mercer

I'm a Business Intelligence and Data Warehousing consultant based in Brisbane, Australia. I've consulted on or managed several large BI systems in New Zealand, Australia and Latin America.

Contact Info

Please use the contact form on this site.
Or phone 04 5704 1640 (Australia)

Latest Photo

Old-timer with a machine gun. Vintage War truck in 2015 ANZAC Day. Flag with original Australian (and ANZAC) colours is held in the background.

Tags: OCI8, PHP, Apache, Oracle, Mac