<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Installation</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="oci8.requirements.html">Requirements</a></div>
<div class="next" style="text-align: right; float: right;"><a href="oci8.test.html">Testing</a></div>
<div class="up"><a href="oci8.setup.html">Installing/Configuring</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="oci8.installation" class="section">
<h2 class="title">Installation</h2>
<div class="section" id="oci8.configure">
<h2 class="title">Configuring PHP with OCI8</h2>
<p class="para">
Review the
previous <a href="oci8.requirements.html" class="link">Requirements</a>
section before configuring OCI8.
</p>
<p class="para">
To enable the OCI8 extension, configure PHP with the option
<strong class="option configure">--with-oci8</strong>
.
</p>
<p class="para">
Before starting the web server, OCI8 typically requires several
Oracle environment variables (see below) to locate libraries, point
to configuration files, and set some basic properties such as the
character set used by Oracle libraries. The variables must be set
<em class="emphasis">before</em> any PHP process starts.
</p>
<p class="para">
The PHP binary must link with the same, or more recent, major version of
Oracle libraries as it was configured with. For example, if you build
OCI8 with Oracle 11.2 libraries, then PHP should also be deployed
and run with Oracle 11.2 libraries. PHP applications can connect to other
versions of Oracle Database, since Oracle has client-server cross-version compatibility.
</p>
</div>
<div class="section">
<h2 class="title">Installing OCI8 as a Shared Extension</h2>
<p class="para">
The configuration <em>shared</em> option
builds OCI8 as a shared library that can be dynamically loaded into
PHP. Building a shared extension allows OCI8 to be upgraded easily
without impacting the rest of PHP.
</p>
<p class="para">
Configure OCI8 using one of the following configure options.
</p>
<p class="para">
<ul class="itemizedlist">
<li class="listitem">
<p class="para">
If using the free <a href="http://www.oracle.com/technetwork/database/features/instant-client/index-100365.html" class="link external">» Oracle Instant
Client</a> libraries, then do:
</p>
<p class="para">
<div class="informalexample">
<div class="example-contents screen">
<div class="cdata"><pre>
./configure --with-oci8=shared,instantclient,/path/to/instant/client/lib
</pre></div>
</div>
</div>
</p>
<p class="para">
If Instant Client is installed from ZIP files, make sure to create
the library symbolic link first, for example <em>ln -s
libclntsh.so.12.1 libclntsh.so</em>.
</p>
<p class="para">
If using an RPM-based installation of Oracle Instant Client, the
configure line will look like this:
</p>
<p class="para">
<div class="informalexample">
<div class="example-contents screen">
<div class="cdata"><pre>
./configure --with-oci8=shared,instantclient,/usr/lib/oracle/<version>/client/lib
</pre></div>
</div>
</div>
</p>
<p class="para">
For example, <strong class="option configure">--with-oci8=shared,instantclient,/usr/lib/oracle/12.1/client/lib</strong>
</p>
<p class="para">
Note that Oracle Instant Client support first appeared in PHP
4.3.11 and 5.0.4 and originally used the option
<strong class="option configure">--with-oci8-instant-client</strong>
to
configure PHP.
</p>
</li>
<li class="listitem">
<p class="para">
If using an Oracle database or full Oracle Client installation then do:
</p>
<p class="para">
<div class="informalexample">
<div class="example-contents screen">
<div class="cdata"><pre>
./configure --with-oci8=shared,$ORACLE_HOME
</pre></div>
</div>
</div>
</p>
<p class="para">
Make sure the web server user
(<em>nobody</em>, <em>www</em>) has access to
the libraries, initialization files
and <var class="filename">tnsnames.ora</var> (if used) under
the <em>$ORACLE_HOME</em> directory. With Oracle
10<em class="emphasis">g</em>R2, you may need to run
the <var class="filename">$ORACLE_HOME/install/changePerm.sh</var>
utility to give directory access.
</p>
</li>
</ul>
</p>
<p class="para">
After configuration, follow the usual PHP building procedure,
e.g. <em class="emphasis">make install</em>. The OCI8 shared extension
<var class="filename">oci8.so</var> library will be created. It may need
to be manually moved to the PHP extension directory, specified by
the <a href="ini.core.html#ini.extension-dir" class="link">extension_dir</a> option in
your <var class="filename">php.ini</var> file.
</p>
<p class="para">
To complete installation of OCI8, edit <var class="filename">php.ini</var> and add the line:
</p>
<p class="para">
<div class="informalexample">
<div class="example-contents screen">
<div class="cdata"><pre>
extension=oci8.so
</pre></div>
</div>
</div>
</p>
</div>
<div class="section">
<h2 class="title">Installing OCI8 as a Statically Compiled Extension</h2>
<p class="para">
Configure PHP to include OCI8 using one of the following configure options.
</p>
<p class="para">
<ul class="itemizedlist">
<li class="listitem">
<p class="para">
If using Oracle Instant Client, then do:
</p>
<p class="para">
<div class="informalexample">
<div class="example-contents screen">
<div class="cdata"><pre>
./configure --with-oci8=instantclient,/path/to/instant/client/lib
</pre></div>
</div>
</div>
</p>
</li>
<li class="listitem">
<p class="para">
If using an Oracle database or full Oracle Client installation then do:
</p>
<p class="para">
<div class="informalexample">
<div class="example-contents screen">
<div class="cdata"><pre>
./configure --with-oci8=$ORACLE_HOME
</pre></div>
</div>
</div>
</p>
</li>
</ul>
</p>
<p class="para">
After configuration, follow the usual PHP building procedure,
e.g. <em class="emphasis">make install</em>. After successful
compilation, you do not need to add <var class="filename">oci8.so</var> to
<var class="filename">php.ini</var>. No additional build steps are required.
</p>
</div>
<div class="section">
<h2 class="title">Installing OCI8 from PECL</h2>
<p class="para">
The OCI8 extension can be added to an existing PHP installation
either automatically or manually
from <a href="http://pecl.php.net/package/oci8" class="link external">» PECL</a>.
</p>
<p class="para">
For an automated install follow these steps:
</p>
<p class="para">
<ul class="itemizedlist">
<li class="listitem">
<p class="para">
If you are behind a firewall, set PEAR's proxy, for example:
</p>
<p class="para">
<div class="informalexample">
<div class="example-contents screen">
<div class="cdata"><pre>
pear config-set http_proxy http://my-proxy.example.com:80/
</pre></div>
</div>
</div>
</p>
</li>
<li class="listitem">
<p class="para">
Run
</p>
<p class="para">
<div class="informalexample">
<div class="example-contents screen">
<div class="cdata"><pre>
pecl install oci8
</pre></div>
</div>
</div>
</p>
<p class="para">
When prompted, enter either the value of <em>$ORACLE_HOME</em>, or
<em>instantclient,/path/to/instant/client/lib</em>.
</p>
<p class="para">
Note: Do not enter the variable <em>$ORACLE_HOME</em>
because it will not be expanded. Instead, enter the actual path
of the Oracle home directory.
</p>
</li>
</ul>
</p>
<p class="para">
For a manual install when the <em>pecl</em> command is not
available, download the PECL OCI8 package, e.g. <var class="filename">oci8-1.4.10.tgz</var>.
</p>
<p class="para">
<ul class="itemizedlist">
<li class="listitem">
<p class="para">
Extract the package:
</p>
<p class="para">
<div class="informalexample">
<div class="example-contents screen">
<div class="cdata"><pre>
tar -zxf oci8-1.4.10.tgz
cd oci8-1.4.10
</pre></div>
</div>
</div>
</p>
</li>
<li class="listitem">
<p class="para">
Prepare the package:
</p>
<p class="para">
<div class="informalexample">
<div class="example-contents screen">
<div class="cdata"><pre>
phpize
</pre></div>
</div>
</div>
</p>
</li>
<li class="listitem">
<p class="para">
Configure the package, either
using <em>$ORACLE_HOME</em> or Instant Client
</p>
<p class="para">
<div class="informalexample">
<div class="example-contents screen">
<div class="cdata"><pre>
./configure -with-oci8=shared,$ORACLE_HOME
</pre></div>
</div>
</div>
</p>
<p class="para">
or
</p>
<p class="para">
<div class="informalexample">
<div class="example-contents screen">
<div class="cdata"><pre>
./configure -with-oci8=shared,instantclient,/path/to/instant/client/lib
</pre></div>
</div>
</div>
</p>
</li>
<li class="listitem">
<p class="para">
Install the package:
</p>
<p class="para">
<div class="informalexample">
<div class="example-contents screen">
<div class="cdata"><pre>
make install
</pre></div>
</div>
</div>
</p>
</li>
</ul>
</p>
<p class="para">
After either an automatic or manual install, edit your <var class="filename">php.ini</var>
file and add the line:
</p>
<p class="para">
<div class="informalexample">
<div class="example-contents screen">
<div class="cdata"><pre>
extension=oci8.so
</pre></div>
</div>
</div>
</p>
<p class="para">
Make sure the <var class="filename">php.ini</var>
directive <a href="ini.core.html#ini.extension-dir" class="link">extension_dir</a> is
set to the directory that <var class="filename">oci8.so</var> was installed
in.
</p>
</div>
<div class="section">
<h2 class="title">Installing OCI8 on Windows</h2>
<p class="para">
When using Oracle 10<em class="emphasis">g</em>R2 client libraries on
Windows, uncomment the <var class="filename">php.ini</var>
line <em>extension=php_oci8.dll</em>. When using Oracle
11<em class="emphasis">g</em>R2 or later client libraries, uncomment
<em>extension=php_oci8_11g.dll</em>
or <em>extension=php_oci8.dll</em>. With Oracle
12<em class="emphasis">c</em> libraries
use <em>extension=php_oci8_12c.dll</em>
or <em>extension=php_oci8_11g.dll</em>
or <em>extension=php_oci8.dll</em>. Only one of these DLLs
may be enabled at a time. DLLs with higher versions may contain more
functionality. Not all DLLs may be available for all versions of
PHP. Make
sure <a href="ini.core.html#ini.extension-dir" class="link">extension_dir</a> is set
to the directory containing the PHP extension DLLs.
</p>
<p class="para">
If using Instant Client, set the system <em>PATH</em>
environment variable to the Oracle library directory.
</p>
</div>
<div class="section">
<h2 class="title">Setting the Oracle Environment</h2>
<p class="para">
Before using this extension, make sure that the Oracle environment
variables are properly set for the web daemon user. If your web
server is automatically started at boot time then make sure that the
boot-time environment is also configured correctly.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
Do not set Oracle environment variables
using <span class="function"><a href="function.putenv.html" class="function">putenv()</a></span> in a PHP script because Oracle
libraries may be loaded and initialized before your script
runs. Variables set with <span class="function"><a href="function.putenv.html" class="function">putenv()</a></span> may then cause
conflicts, crashes, or unpredictable behavior. Some functions may
work but others might give subtle errors. The variables should be
set up <em class="emphasis">before</em> the web server is started.
</p>
</p></blockquote>
<p class="para">
On Red Hat Linux and variants, export variables at the end of
<var class="filename">/etc/sysconfig/httpd</var>. Other systems with
Apache 2 may use an <var class="filename">envvars</var> script in the
Apache <var class="filename">bin</var> directory. A third option, the
Apache <em>SetEnv</em> directive
in <var class="filename">httpd.conf</var>, may work in some systems but is
known to be insufficient in others.
</p>
<p class="para">
To check that environment variables are set correctly,
use <span class="function"><a href="function.phpinfo.html" class="function">phpinfo()</a></span> and check
the <em class="emphasis">Environment</em> (not the <em class="emphasis">Apache
Environment</em>) section contains the expected variables.
</p>
<p class="para">
The variables that might be needed are included in the following
table. Refer to the Oracle documentation for more information on
all the available variables.
<table class="doctable table">
<caption><strong>Common Oracle Environment Variables</strong></caption>
<thead>
<tr>
<th>Name</th>
<th>Purpose</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>ORACLE_HOME</td>
<td>Contains the directory of the full Oracle Database
software. Do not set this when using Oracle Instant Client as
it is unnecessary and may cause installation problems.</td>
</tr>
<tr>
<td>ORACLE_SID</td>
<td>Contains the name of the database on the local machine to
be connected to. There is no need to set this if you using
Oracle Instant Client, or always pass the connection parameter
to <span class="function"><a href="function.oci-connect.html" class="function">oci_connect()</a></span>.</td>
</tr>
<tr>
<td>LD_LIBRARY_PATH</td>
<td>Set this (or its platform equivalent, such
as <em>DYLD_LIBRARY_PATH</em>, <em>LIBPATH</em>,
or <em>SHLIB_PATH</em>) to the location of the Oracle
libraries, for example <var class="filename">$ORACLE_HOME/lib</var>
or <var class="filename">/usr/lib/oracle/11.1/client/lib</var>. This
variable is not needed if the libraries are located by a
different search mechanism, such as
with <var class="filename">ldconfig</var> or
with <em>LD_PRELOAD</em>.</td>
</tr>
<tr>
<td>NLS_LANG</td>
<td>This is the primary variable for setting the character
set and globalization information used by the Oracle
libraries.</td>
</tr>
<tr>
<td>ORA_SDTZ</td>
<td>Sets the Oracle session timezone.</td>
</tr>
<tr>
<td>TNS_ADMIN</td>
<td>Contains the directory where the Oracle Net Services
configuration files such as <var class="filename">tnsnames.ora</var>
and <var class="filename">sqlnet.ora</var> are kept. Not needed if
the <span class="function"><a href="function.oci-connect.html" class="function">oci_connect()</a></span> connection string uses the
Easy Connect naming syntax such
as <em>localhost/XE</em>. Not needed if the network
configuration files are in one of the default locations such
as <var class="filename">$ORACLE_HOME/network/admin</var>
or <var class="filename">/etc</var>.</td>
</tr>
</tbody>
</table>
Less frequently used Oracle environment variables include
<em>TWO_TASK</em>, <em>ORA_TZFILE</em>, and the
various Oracle globalization settings
like <em>NLS*</em> and the <em>ORA_NLS_*</em>
variables.
</p>
</div>
<div class="section">
<h2 class="title">Troubleshooting</h2>
<p class="para">
The most common problem with installing OCI8 is not having the
Oracle environment correctly set. This typically appears as a
problem using <span class="function"><a href="function.oci-connect.html" class="function">oci_connect()</a></span>
or <span class="function"><a href="function.oci-pconnect.html" class="function">oci_pconnect()</a></span>. The error may be a PHP error
such as <em class="emphasis">Call to undefined function
oci_connect()</em>, an Oracle error such as ORA-12705, or even
an Apache crash. Check the Apache log files for startup errors and
see the sections above to resolve this problem.
</p>
<p class="para">
While network errors like ORA-12154 or ORA-12514 indicate an Oracle
network naming or configuration issue, the root cause may be because
the PHP environment is incorrectly set up and Oracle libraries are
unable to locate the <var class="filename">tnsnames.ora</var> configuration
file.
</p>
<p class="para">
On Windows, having multiple versions of Oracle on the one machine
can easily cause library clashes unless care is taken to make sure
PHP only uses the correct version of Oracle.
</p>
<p class="para">
A utility to examine what libraries are being looked for and loaded
can help resolve missing or clashing library issues, particularly on
Windows.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<strong>If the web server doesn't start or crashes at
startup</strong><br />
<p class="para">
Check that Apache is linked with the pthread library:
</p>
<p class="para">
<div class="informalexample">
<div class="example-contents screen">
<div class="cdata"><pre>
# ldd /www/apache/bin/httpd
libpthread.so.0 => /lib/libpthread.so.0 (0x4001c000)
libm.so.6 => /lib/libm.so.6 (0x4002f000)
libcrypt.so.1 => /lib/libcrypt.so.1 (0x4004c000)
libdl.so.2 => /lib/libdl.so.2 (0x4007a000)
libc.so.6 => /lib/libc.so.6 (0x4007e000)
/lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
</pre></div>
</div>
</div>
</p>
<p class="para">
If the libpthread is not listed, then reinstall Apache:
</p>
<p class="para">
<div class="informalexample">
<div class="example-contents screen">
<div class="cdata"><pre>
# cd /usr/src/apache_1.3.xx
# make clean
# LIBS=-lpthread ./config.status
# make
# make install
</pre></div>
</div>
</div>
</p>
<p class="para">
Please note that on some systems like UnixWare, it is libthread
instead of libpthread. PHP and Apache have to be configured with
EXTRA_LIBS=-lthread.
</p>
</p></blockquote>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="oci8.requirements.html">Requirements</a></div>
<div class="next" style="text-align: right; float: right;"><a href="oci8.test.html">Testing</a></div>
<div class="up"><a href="oci8.setup.html">Installing/Configuring</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
