Installing PHP and the Oracle Instant Client for Linux and Windows

Author: Christopher Jones, Oracle Corporation
Email: christopher.jones@oracle.com
Updated: March 2009

Oracle 11g Instant Client is the easiest way to connect PHP to a remote Oracle database. This notes describes how to install PHP with the OCI8 Extension and Oracle Instant Client on Windows and Linux. The free The Underground PHP and Oracle Manual contains more detail and explains other installation options.

OCI8 is the PHP extension for connecting to Oracle databases. (The name is copied from Oracle's C "call interface" API interface first introduced in Oracle 8.) OCI8 is open source and included with PHP.

Oracle Instant Client is a free set of easily installed libraries that allow programs to connect to Oracle databases. To use Instant Client, an existing database is needed; Instant Client does not include one. Typically the database will be on another machine. If the database is local then Oracle libraries will generally be accessible and Instant Client not required.

Using Instant Client 11g, OCI8 functions work with Oracle 9.2, 10.x, and 11.x databases. If OCI8 is compiled with Instant Client 10g, connection to Oracle 8.1 is also possible.

Software Requirements:

Enabling the PHP OCI8 Extension on Windows

The Instant Client binaries complement PHP's prebuilt binaries for Windows.

1. Download the Apache HTTPD Server and the Windows PHP 5.2 zip package. Use the "Non-thread-safe" version of PHP if you want to use Fast CGI, or use the default bundle if you plan to run PHP as an Apache module.

   Install PHP and Apache following Installation on Windows Systems in the PHP Manual.

   Check that PHP is working before continuing. At this stage Oracle support is not enabled.

2. Download the "Instant Client Package - Basic" for Windows from the OTN Instant Client page.

   Unzip the Instant Client to c:\instantclient_11_1

   Edit the PATH environment setting and add c:\instantclient_11_1 before any other Oracle directories. For example, on Windows XP, follow Start -> Control Panel -> System -> Advanced -> Environment Variables and edit PATH in the System variables list.

   Set desired Oracle globalization language environment variables such as NLS_LANG. If nothing is set, a default local environment will be assumed. See An Overview on Globalizing Oracle PHP Applications for more details.

   Unset Oracle variables such as ORACLE_HOME and ORACLE_SID, which are unnecessary with Instant Client.

3. The default OCI8 1.2 extension included in PHP 5.2 has been superceded. Whilst you could use it, I recommend downloading the OCI8 1.3 extension from Pierre Joye's build page. This download location is temporary while the PHP community develops a replacement for the pecl4win system.

   The current OCI8 1.3 packages for PHP 5.2 are php_oci8-1.3.5-5.2-Win32-vc6-x86.zip and php_oci8-1.3.5-5.2-nts-Win32-vc6-x86.zip. Use the "nts" version if you installed a non-thread-safe PHP. Each package contains a replacement php_oci8.dll and introduces a new php_oci8_11g.dll file.

   Unzip the appropriate package and move the two DLLs to your extension directory, e.g. c:\php-5.2.9\ext.

4. Edit php.ini and set extension_dir to the directory with the PHP extension DLLs:

   extension_dir="c:\php-5.2.9\ext"
   
   

   Also in php.ini, enable the OCI8 extension with:

   extension=php_oci8_11g.dll
   
   

   If using Oracle 10.2 Instant Client, alternatively put:

   extension=php_oci8.dll
   
   

   Only one of the php_oci8.dll or php_oci8_11g.dll extensions can be enabled at any time. The extensions are mostly equivalent, but the 11g version supports Oracle DRCP connection pooling.

5. Restart Apache.

Enabling the PHP OCI8 Extension on Linux

To install on Linux, PHP generally needs to be recompiled. For users of Oracle Enterprise Linux, pre-built RPM packages of PHP and OCI8 are available from oss.oracle.com, or via ULN updates.

To build PHP and OCI8:

1. Download the Apache HTTPD Server if you decide not to use your default package. Download the PHP 5.2 source code.

   Install PHP and Apache following Installation on Unix systems in the PHP manual.

   At this stage, don't configure the OCI8 extension.

   Check that PHP is working before continuing.

2. Download the Basic and the SDK Instant Client packages from the OTN Instant Client page. Either the zip file or RPMs can be used.

   Install the RPMs as the root user:

   rpm -Uvh oracle-instantclient11.1-basic-11.1.0.7.0-1.i386.rpm
   rpm -Uvh oracle-instantclient11.1-devel-11.1.0.7.0-1.i386.rpm
   

   The first RPM puts the Oracle libraries in /usr/lib/oracle/11.1/client/lib and the second creates headers in /usr/include/oracle/11.1/client

   If using the zip files, the SDK should unzipped to the same directory as the basic package, and a symbolic link created:

   ln -s libclntsh.so.11.1 libclntsh.so

3. The latest OCI8 1.3 extension from PECL supercedes the default version in the PHP 5.2 source code. This can be downloaded manually and installed with:

   pecl install oci8-1.3.5.tgz
   

   Or the latest production package can be automatically downloaded and installed:

   pecl install oci8
   

   This gives:

   downloading oci8-1.3.5.tgz ...
   Starting to download oci8-1.3.5.tgz (137,987 bytes)
   .....done: 137,987 bytes
   10 source files, building
   running: phpize
   Configuring for:
   PHP Api Version:         20041225
   Zend Module Api No:      20060613
   Zend Extension Api No:   220060519
    1. 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
   
   1-1, 'all', 'abort', or Enter to continue: 
   

   If you have the Instant Client RPMs, hit Enter and PECL will automatically locate the RPMs and build and install an oci8.so shared library.

   If you have the Instant Client zip files, or have multiple versions of the Instant Client RPMs installed then explicitly give the path:

   • Enter 1 to update the first (and only) setting. The OCI8 configuration prompt will then be shown:

     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] : 
     

   • Enter the path, such as:

     instantclient,/usr/lib/oracle/11.1/client/lib
     

     or:

     instantclient,/your/path/to/instantclient_11_1 
     

     Do not use any environment variable names, because the PECL installer doesn't expand variables.

   • You will get reprompted 1-1, 'all', 'abort', or Enter to continue. As it says, press Enter to continue. PECL will build and install an oci8.so shared library.

4. Edit php.ini and confirm extension_dir points to the directory the oci8.so file was installed into.

   Also in php.ini, enable the OCI8 extension with:

   extension=oci8.so
   
   

5. Add the directory with Instant Client to /etc/ld.so.conf, or manually set LD_LIBRARY_PATH to /usr/lib/oracle/11.1/client/lib and restart Apache.

   It is important to set all Oracle environment variables before starting Apache. A script helps do that:

   #!/bin/sh
   
   LD_LIBRARY_PATH=/usr/lib/oracle/11.1/client/lib:${LD_LIBRARY_PATH}
   export LD_LIBRARY_PATH
   
   echo Starting Apache 
   /usr/sbin/apachectl start
   

   This script can contain desired Oracle globalization language environment variables such as NLS_LANG. If nothing is set, a default local environment will be assumed. See An Overview on Globalizing Oracle PHP Applications for more details.

Verifying the Extension is Installed

To check the extension is configured, create a simple PHP script phpinfo.php in the Apache document root:

<?php
  phpinfo();
?>

Load the script into a browser using the appropriate URL, e.g. "http://localhost/phpinfo.php". The browser page will contain an "oci8" section saying "OCI8 Support enabled".

The OCI8 options that can be configured in your php.ini file are shown.

Connecting to Oracle

Oracle authentication and database information is passed to oci_connect() to create a connection. Tools linked with Instant Client are always "remote" from any database server and an Oracle Net connection identifier must be used along with a username and password. The connection information is likely to be well known for established Oracle databases. With new systems the information is given by the Oracle installation program when the database is set up. The installer should have configured Oracle Net and created a service name.

$c = oci_connect('hr', 'hr_password', '//mymachine.mydomain/MYDB');

See Oracle's Using the Easy Connect Naming Method documentation for the Easy Connect syntax.

In new databases the demonstration schemas such as the HR user may need to be unlocked and given a password. This may be done in SQL*Plus by connecting as the SYSTEM user and executing the statement:

ALTER USER username IDENTIFIED BY new_password ACCOUNT UNLOCK;

Using Oracle

Try out a simple script, testoci.php. Modify the connection details to suit your database and load it in a browser. This example lists all tables owned by the user HR:

<?php

$conn = oci_connect('hr', 'hr_password', 'mymachine.mydomain/MYDB');

$query = 'select table_name from user_tables';

$stid = oci_parse($conn, $query);
oci_execute($stid, OCI_DEFAULT);
while ($row = oci_fetch_array($stid, OCI_ASSOC)) {
  foreach ($row as $item) {
    echo $item." ";
  }
  echo "<br>\n";
}

oci_free_statement($stid);
oci_close($conn);

?>

Troubleshooting

Check the Apache error log file for startup errors.

Temporarily set display_error=On in php.ini so script errors are displayed.

Chapter 9 of The Underground PHP and Oracle Manual contains some common connection errors.

Oracle's SQL*Plus command line tool can be downloaded from the Instant Client page to help resolve environment and connection problems.

Check the environment used by SQL*Plus is the same as shown by phpinfo.php.

Windows Help

If the phpinfo.php script does not produce an "oci8" section saying "OCI8 Support enabled", verify that extension=php_oci8_11g.dll is uncommented in php.ini.

If PATH is set incorrectly or the Oracle libraries cannot be found, starting Apache will give an alert: "The dynamic link library OCI.dll could not be found in the specified path." The Environment section of the phpinfo() page will show the values of PATH and the Oracle variables actually being used by PHP.

If php.ini's extension_dir directive is not correct, Apache startup will give an alert: "PHP Startup: Unable to load dynamic library php_oci8.dll."

Linux Help

If using Instant Client zip files, make sure the two packages are unzipped at the same time. Make sure a symbolic link libclntsh.so points to libclntsh.so.11.1

Set all required Oracle environment variables in the shell that starts Apache.

Conclusion

Installing Oracle Instant Client and PHP OCI8 from PECL provide maximum flexibility, allowing components to be easily installed and upgraded.

If space is at a premium, the Instant Basic Lite package can be used instead of the Basic package, and the ODBC, JDBC and OCCI components removed.

The future PHP 5.3 release will include the OCI8 1.3 extension by default.

The PHP Developer Center contains links to useful background material.