Installing PHP and the Oracle 10g Instant Client for Linux and Windows
Author: Christopher Jones, Consulting Technical Staff, Oracle Corporation
Publication Date: December 2004
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. An existing Oracle database is needed; Instant Client does not come with 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
Download the "Instant Client Package - Basic." On Linux, also download the "Instant Client Package - SDK."
The PHP community still recommends Apache 1.3
[url=http://www.php.net]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.
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 Open Source Developer Center contains links to useful background material such as "Installing Oracle, [url=http://www.php.net]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.
Download the Instant Client Basic package for Windows from the Instant Client page on OTN. The zip file is about 30MB in size.
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.
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 [url=http://www.php.net]PHP Applications for more details.
Unset unnecessary Oracle variables such as ORACLE_HOME and ORACLE_SID.
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".
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".
Enabling the PHP OCI8 Extension on Linux
To add Oracle connectivity on Linux, PHP needs to be recompiled.
The Open Source Developer Center contains links to useful background material such as Installing Oracle, [url=http://www.php.net]PHP, and Apache on Linux, which covers installation of a traditional, full Oracle 10g footprint (which is not required with Instant Client).
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
Download PHP and untar it.
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.
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
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 [url=http://www.php.net]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.
Rebuild the "configure" script in the top-level PHP directory. cd php-4.3.9
rm -rf autom4te.cache config.cache
./buildconf --force
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
Rebuild PHP.
make
make install
Copy the PHP configuration to the location given by --with-config-file-path
cp php.ini-recommended $HOME/apache/conf/php.ini
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
To confirm 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 a URL similar to "http://localhost:8888/<path>/phpinfo.php". The browser page should contain an "oci8" section saying "OCI8 Support enabled".
Connecting to Oracle
Oracle connection information is passed to OCILogon() 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.
In new databases the demonstration schemas such as the HR user may need to be unlocked and given a password. This may also be done in SQL*Plus by connecting as the SYSTEM user and executing the statement:
ALTER USER username IDENTIFIED BY new_password ACCOUNT UNLOCK;
There are several ways to pass the connection information to PHP. This first example uses Oracle 10g'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: $c = OCILogon('hr', 'hr_password', '//mymachine.mydomain/MYDB');
See Oracle's Using the Easy Connect Naming Method documentation for the Easy Connect syntax.
Alternatively, if /home/tnsnames.ora contains: 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');
If the environment variable LOCAL (on Windows) or TWO_TASK (on Linux) was set to MYDB then a connection to MYDB could also be made with: $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);
?>
Troubleshooting
The Oracle [url=http://www.php.net]PHP Troubleshooting FAQ contains helpful information on connecting to Oracle.
Oracle's SQL*Plus command line tool can be downloaded from the Instant Client page to help resolve environment and connection problems. Also see the SQL*Plus Instant Client Release Notes.
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.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
Carefully check config.m4 was patched correctly. If "configure" fails, check the config.log file. Revert config.m4, remove caches files, run ./buildconf --force and configure, and verify that the problems are related to the changes made.
Make sure the timestamp on "configure" is current. Remove any cache files and rebuild it if necessary.
Set all required Oracle environment variables in the shell that starts Apache.
Conclusion
I hope this article has been helpful. Questions and suggestions can be posted on the OTN Instant Client or [url=http://www.php.net]PHP forums.
