Installing PHP and the Oracle 10g Instant Client for Linux and Windows

updated for PHP 5.1.2

Oracle 10g Instant Client (free download available) is the easiest way for PHP to connect to a remote Oracle database, requiring installation of only three libraries.

The Instant Client libraries used by PHP access Oracle's current API, called OCI8. (This C interface takes its name from being first introduced in Oracle8.) PHP Oracle 8 Functions can call Oracle 8.1.7, 9.x, or 10.x directly, or optional abstraction classes like PEAR MDB2 and ADOdb can be used for convenience.

The older PHP "oracle" extension can also be used with Instant Client but it calls a deprecated Oracle API. New development with this extension is not recommended by the PHP community or by Oracle.

To use Instant Client with PHP 4 or 5 on Apache, follow the steps below. (See this section for details about 5.1.2 and its refactored OCI8 extension.) An existing Oracle database is needed; Instant Client does not include one.

Typically the database will be on another machine. If the database is local then Oracle components will generally already be available and Instant Client is not required.

Software Requirements:

Software	Notes
Oracle Instant Client	Download the "Instant Client Package - Basic." On Linux, also download the "Instant Client Package - SDK."
Apache HTTPD Server	The PHP community still recommends Apache 1.3
PHP - PHP Hypertext Processor	Version 4.3 or later

Enabling the PHP OCI8 Extension on Windows

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

1. Download the PHP binary zip file (not the installer build) and Apache. Install them following Installation on Windows Systems in the PHP Manual. OTN's PHP Developer Center contains links to useful background material such as "Installing Oracle, PHP, and Apache on Windows 2000/XP," which covers installation of a traditional, full Oracle 10g footprint (which is not required with Instant Client).

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

2. Download the Instant Client Basic package for Windows from the Instant Client page on OTN. The zip file is about 30MB in size.

3. Create a subdirectory (e.g., c:\instantclient10_1) and copy these libraries from the zip file:

   • oraociei10.dll
   • orannzsbb10.dll
   • oci.dll

   Collectively these three files are about 80MB in size.

   To use PHP's older "oracle" extension (enabled with "extension=php_oracle.dll" in php.ini), copy ociw32.dll instead of oci.dll.

4. Edit the environment and add c:\instantclient10_1 to PATH before any other Oracle directories.

   For example, on Windows 2000, follow Start -> Settings -> Control Panel -> System -> Advanced -> Environment Variables and edit PATH in the System variables list.

   If a tnsnames.ora file is used to define Oracle Net service names, copy tnsnames.ora to c:\instantclient10_1 and set the user environment variable TNS_ADMIN to c:\instantclient10_1. A default service name can optionally be set in the user environment variable LOCAL.

   Set necessary 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 unnecessary Oracle variables such as ORACLE_HOME and ORACLE_SID.

5. Edit php.ini and uncomment the OCI8 extension:

   extension=php_oci8.dll
   

   Set the extension_dir directive to the full PHP extension DLL path. In PHP 4 the DLLs are in the "extensions" sub-directory of the PHP software. In PHP 5 they are in "ext".

6. Restart Apache.

To check the extension is configured, create a simple PHP script phpinfo.php where the web server can read it.

<?php
  phpinfo();
?>

Load the script into a browser using an "http://" URL. The browser page should contain an "oci8" section saying "OCI8 Support enabled".

To add Oracle connectivity on Linux, PHP needs to be recompiled.

The PHP Developer Center contains links to useful background material such as Installing Oracle, PHP, and Apache on Linux, which covers installation of a traditional, full Oracle 10g footprint (which is not required with Instant Client).

1. Download and install Apache. For example, to install it in your home directory:

   cd apache_1.3.31
   ./configure --enable-module=so --prefix=$HOME/apache --with-port=8888
   make
   make install
   

   Edit $HOME/apache/conf/httpd.conf and add:

   AddType application/x-httpd-php        .php
   AddType application/x-httpd-php-source .phps
   

2. Download PHP and untar it.
3. Download the Basic and the SDK Instant Client packages from the Instant Client page on OTN. Collectively the two RPMs are about 30MB in size.
4. Install the RPMs as the root user.

   rpm -Uvh oracle-instantclient-basic-10.1.0.3-1.i386.rpm
   rpm -Uvh oracle-instantclient-devel-10.1.0.3-1.i386.rpm
   

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

5. Backup and then apply this patch to PHP's ext/oci8/config.m4. The patch line numbers are based on PHP 4.3.9. This patch will not be necessary when PHP bug 31084 is fixed, most likely in PHP 4.3.11 and 5.0.4.

   If you are using PHP 4.3.9 or 4.3.10 you can save the patch to a file, e.g. php_oci8ic_buildpatch, and install it using:

   patch -u config.m4 php_oci8ic_buildpatch
   

   The patch creates a new PHP configuration parameter: --with-oci8-instant-client[=DIR]. On Linux, by default, it uses the latest version of the Instant Client installed from the RPMs. A directory to the Oracle libraries can be specified to use a different version. In either case, the correct SDK headers will automatically be used.

   The new parameter is mutally exclusive with the existing --with-oci8 parameter.

   For reference: on non-Linux platforms, the Instant Client package is unzipped into a directory of your choice. The --with-oci8-instant-client parameter will need this directory explicitly specified; for example, --with-oci8-instant-client=/home/instantclient10_1. The Instant Client SDK should unzipped to the same directory as the basic package so the subdirectory of header files can be located by the revised configuration script.

6. Rebuild the "configure" script in the top-level PHP directory.

   cd php-4.3.9
   rm -rf autom4te.cache config.cache
   ./buildconf --force
   

7. Run configure with the new option. This example uses Apache installed in the home directory.

      ./configure \
         --with-oci8-instant-client \
         --prefix=$HOME/php --with-apxs=$HOME/apache/bin/apxs \
         --enable-sigchild --with-config-file-path=$HOME/apache/conf
   

8. Rebuild PHP.

   make
   make install
   

9. Copy the PHP configuration to the location given by --with-config-file-path

   cp php.ini-recommended $HOME/apache/conf/php.ini
   

10. Set LD_LIBRARY_PATH to /usr/lib/oracle/10.1.0.3/client/lib and restart Apache.

    If a tnsnames.ora file is used to define Oracle Net service names, set TNS_ADMIN to the directory containing the file.

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

    #!/bin/sh
    
    APACHEHOME=/home/apache
    
    LD_LIBRARY_PATH=/usr/lib/oracle/10.1.0.3/client/lib:${LD_LIBRARY_PATH}
    TNS_ADMIN=/home
    export LD_LIBRARY_PATH TNS_ADMIN
    
    echo Starting Apache 
    $APACHEHOME/apachectl start
    

<?php
  phpinfo();
?>

Load the script into a browser using a URL similar to "http://localhost:8888/<path>/phpinfo.php". The browser page should contain an "oci8" section saying "OCI8 Support enabled".

ALTER USER username IDENTIFIED BY new_password ACCOUNT UNLOCK;

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

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

MYDB =
 (DESCRIPTION =
   (ADDRESS = (PROTOCOL = TCP)(HOST = mymachine.mydomain)(PORT = 1521))
   (CONNECT_DATA =
      (SERVER = DEDICATED)
      (SERVICE_NAME = MYDB)
    )
  )

and the TNS_ADMIN environment variable was set to /home (before starting Apache), then the connection string could be:

$c = OCILogon('hr', 'hr_password', 'MYDB');

      

$c = OCILogon('hr', 'hr_password');

Using Oracle

When the basic connection is working, 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 = OCILogon("hr", "hr_password", '//mymachine.mydomain:port/MYDB);

$query = 'select table_name from user_tables';

$stid = OCIParse($conn, $query);
OCIExecute($stid, OCI_DEFAULT);
 while ($succ = OCIFetchInto($stid, $row)) {
    foreach ($row as $item) {
      echo $item." ";
    }
    echo "<br>\n";
 }

 OCILogoff($conn);

 ?>

Windows Help

If the phpinfo.php script does not produce an "oci8" section saying "OCI8 Support enabled", verify that "extension=php_oci8.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

For PHP 5.1.2 and Later

The "re-factored" OCI8 extension introduces new syntax for Instant Client support. The re-factored extension was first included in PHP 5.1.2. It is also available from pecl.php.net/package/oci8 and pecl4win.php.net/ext.php/php_oci8.dll for earlier versions of PHP.

If you have installed the Instant Client RPMs as described in this Technical Note, configure PHP with:

./configure \
    --with-oci8=instantclient,/usr/lib/oracle/10.1.0.3/client/lib \
    --prefix=$HOME/php --with-apxs=$HOME/apache/bin/apxs \
    --enable-sigchild --with-config-file-path=$HOME/apache/conf

--with-oci8=instantclient,$HOME/instantclient10_1 

Conclusion

I hope this article has been helpful. Questions and suggestions can be posted on the OTN Instant Client or PHP forums.