http://www.oracle.com/technetwork/articles/technote-php-instant-084410.html
Author: Christopher Jones, Oracle Corporation
Email: christopher.jones@oracle.com
Updated: October 2010
One of the easiest ways to access a remote Oracle database with PHP is to use Oracle Instant Client libraries. This note 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 explains other installation options and contains more detail. If a supported PHP environment is desired use the pre-built Zend Server which includes the OCI8 extension and Oracle Instant Client.
OCI8 is the PHP extension for connecting to Oracle databases. OCI8 is open source and included with PHP. The name is derived from Oracle's C "call interface" API interface first introduced in version 8 of Oracle Database.
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 Instant Client, although convenient and still usable, is generally not needed because OCI8 can directly use the database libraries.
When 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.
To install on Linux, PHP generally needs to be recompiled. For users of Oracle Enterprise Linux, some unsupported pre-built RPM packages of PHP and OCI8 are available from oss.oracle.com, or via Unbreakable Linux Network updates.
To build PHP and OCI8:
Download the Apache HTTPD Server if you decide not to use your default package.
Download the PHP 5.3 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.
Download the Basic and the SDK Instant Client packages from the OTN Instant Client page. Either the zip file or RPMs can be used. Use the 32 bit packages on 32 bit Linux, otherwise use the 64 bit packages.
Install the RPMs as the root user, for example:
rpm -Uvh oracle-instantclient11.2-basic-11.2.0.2.0.x86_64.rpm rpm -Uvh oracle-instantclient11.2-devel-11.2.0.2.0.x86_64.rpm
The first RPM puts Oracle libraries in /usr/lib/oracle/11.2/client64/lib and the second creates headers in /usr/include/oracle/11.2/client64. The 32 bit paths use clientinstead of client64.
If using the zip files, the SDK should unzipped to the same directory as the basic package, and a symbolic link manually created:
The latest OCI8 extension from PECL is always the current version. Although it is generally in sync with the latest PHP 5.3 source code, it can sometimes be more recent. The package can be downloaded in a browser and then installed with:
Or the latest production package can be automatically downloaded and installed:
This gives:
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 want a specific version of Instant Client used, then explicitly give the path:
or:
Edit php.ini and enable the OCI8 extension with:
Also confirm extension_dir points to the directory the oci8.so file was installed into.
Add the Instant Client directory to /etc/ld.so.conf, or manually set LD_LIBRARY_PATH to/usr/lib/oracle/11.2/client64/lib and restart Apache.
It is important to set all Oracle environment variables before starting Apache so that the OCI8 process environment is correctly initialized. Setting environment variables in PHP scripts can lead to obvious or non-obvious problems. A script helps set the variables:
ln -s libclntsh.so.11.1 libclntsh.so
pecl install oci8-1.4.3.tgz
pecl install oci8
downloading oci8-1.4.3.tgz ... Starting to download oci8-1.4.3.tgz (153,515 bytes) ....done: 153,515 bytes 10 source files, building running: phpize Configuring for: PHP Api Version: 20090626 Zend Module Api No: 20090626 Zend Extension Api No: 220090626 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] :
instantclient,/usr/lib/oracle/11.2/client64/lib
instantclient,/your/path/to/instantclient_11_2
extension=oci8.so
#!/bin/sh LD_LIBRARY_PATH=/usr/lib/oracle/11.2/client64/lib:${LD_LIBRARY_PATH} export LD_LIBRARY_PATH echo Starting Apache service httpd 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 the Globalization chapter in The Underground PHP and Oracle Manual for more details.
To check OCI8 configuration, 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" and listing the OCI8 options that can be configured.
Oracle credentials and database information is passed to oci_connect() to create a connection. Tools linked with Instant Client are always considered "remote" from any database server and so an Oracle Database name connection identifier must be used. 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 Network and created a service name.
There are several ways to pass the connection information to PHP. This example uses Oracle's Easy Connect syntax to connect to the HR schema in the MYDB database service running on mymachine. No tnsnames.ora or other Oracle Network file is needed:
$conn = 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;
Try out a simple script, testoci.php Modify the connection credentials 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'); $stid = oci_parse($conn, 'select table_name from user_tables'); oci_execute($stid); echo "<table>\n"; while (($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) != false) { echo "<tr>\n"; foreach ($row as $item) { echo " <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : " ")."</td>\n"; } echo "</tr>\n"; } echo "</table>\n"; ?>
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 information about common connection errors and discusses alternative ways to set environment variables.
Oracle's SQL*Plus command line tool can be downloaded from the Instant Client page to help resolve environment and connection problems. Check SQL*Plus can connect and ensure the Environment section (not the Apache Environment section) of phpinfo.php shows the equivalent environment settings.
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 php.ini's extension_dir directive does not contain the directory with php_oci8_11g.dll then Apache startup will give an alert: "PHP Startup: Unable to load dynamic library php_oci8.dll."
If PATH is not set incorrectly or the Oracle libraries cannot be found at all, 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 there are multiple versions of Oracle libraries on the machine then version clashes are possible. For some discussion on setting variables refer to Using PHP OCI8 with 32-bit PHP on Windows 64-bit.
Linux Help
If using Instant Client zip files, make sure the two packages are unzipped to the same location. 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.
Using Oracle Instant Client and installing PHP OCI8 from PECL provide maximum flexibility, allowing components to be easily installed and upgraded.
Questions and suggestions can be posted on the OTN PHP or Instant Client forums.
The PHP Developer Center contains links to useful background material.