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.
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 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
To confirm the extension is configured, create a simple PHP script phpinfo.php where the web server can read it.
phpinfo();
?>
Load the script into a browser using a URL similar to "http://localhost:8888/
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:
$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 "
\n";
}
OCILogoff($conn);
?>
Troubleshooting
The Oracle 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.
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
If you are using the Instant Client Basic and SDK zip files then change the --with-oci8 option to the unzipped directory, e.g:
--with-oci8=instantclient,$HOME/instantclient10_1
To tell if you have the re-factored extension, check the output of phpinfo(). It will show seven directives with an "oci8." prefix. These are not present in the previous incarnation.
Conclusion
I hope this article has been helpful. Questions and suggestions can be posted on the OTN Instant Client or PHP forums.
By Author: Christopher Jones, Consulting Technical Staff, Oracle Corporation( http://www.oracle.com)
Updated: January 2006
Tidak ada komentar:
Posting Komentar