mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-28 23:08:55 +00:00
9425da2dfa
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@308547 c90b9560-bf6c-de11-be94-00142212c4b1
548 lines
16 KiB
XML
548 lines
16 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<section xml:id="oci8.installation">
|
|
&reftitle.install;
|
|
|
|
|
|
<section xml:id="oci8.configure" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<title>Configuring PHP with OCI8</title>
|
|
<para>
|
|
Review the
|
|
previous <link linkend="oci8.requirements">Requirements</link>
|
|
section before configuring OCI8.
|
|
</para>
|
|
<para>
|
|
To enable the OCI8 extension, configure PHP with the option
|
|
<option role="configure">--with-oci8</option>.
|
|
</para>
|
|
<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 should be set
|
|
<emphasis>before</emphasis> any PHP process starts.
|
|
</para>
|
|
<para>
|
|
PHP should be run 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.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Installing OCI8 as a Shared Extension</title>
|
|
<para>
|
|
The configuration <literal>shared</literal> 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.
|
|
</para>
|
|
<para>
|
|
Configure OCI8 using one of the following configure options.
|
|
</para>
|
|
<para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
If using Oracle Instant Client, then do:
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
./configure --with-oci8=shared,instantclient,/path/to/instant/client/lib
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
If Instant Client is installed from ZIP files, make sure to create
|
|
the library symbolic link, for example <literal>ln -s
|
|
libclntsh.so.11.1 libclntsh.so</literal>.
|
|
</para>
|
|
<para>
|
|
If using an RPM-based installation of Oracle Instant Client, the
|
|
configure line will look like this:
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
./configure --with-oci8=shared,instantclient,/usr/lib/oracle/<version>/client/lib
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
For example, <option role="configure">--with-oci8=shared,instantclient,/usr/lib/oracle/11.2/client/lib</option>.
|
|
</para>
|
|
<para>
|
|
Note that Oracle Instant Client support first appeared in PHP
|
|
4.3.11 and 5.0.4 and originally used the option
|
|
<option role="configure">--with-oci8-instant-client</option> to
|
|
configure PHP.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If using an Oracle database or full Oracle Client installation then do:
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
./configure --with-oci8=shared,$ORACLE_HOME
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
Make sure the web server user
|
|
(<literal>nobody</literal>, <literal>www</literal>) has access to
|
|
the libraries, initialization files
|
|
and <filename>tnsnames.ora</filename> (if used) under
|
|
the <literal>$ORACLE_HOME</literal> directory. With Oracle
|
|
10gR2, you may need to run
|
|
the <filename>$ORACLE_HOME/install/changePerm.sh</filename>
|
|
utility to give directory access.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
After configuration, follow the usual PHP building procedure,
|
|
e.g. <emphasis>make install</emphasis>. The OCI8 shared extension
|
|
<filename>oci8.so</filename> library will be created. It may need
|
|
to be manually moved to the PHP extension directory, specified by
|
|
the <link linkend="ini.extension-dir">extension_dir</link> option in
|
|
your &php.ini; file.
|
|
</para>
|
|
<para>
|
|
To complete installation of OCI8, edit &php.ini; and add the line:
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
extension=oci8.so
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Installing OCI8 as a Statically Compiled Extension</title>
|
|
<para>
|
|
Configure OCI8 using one of the following configure options.
|
|
</para>
|
|
<para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
If using Oracle Instant Client, then do:
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
./configure --with-oci8=instantclient,/path/to/instant/client/lib
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If using an Oracle database or full Oracle Client installation then do:
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
./configure --with-oci8=$ORACLE_HOME
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
After configuration, follow the usual PHP building procedure,
|
|
e.g. <emphasis>make install</emphasis>. After successful
|
|
compilation, you do not need to add <filename>oci8.so</filename> to
|
|
&php.ini;. No additional build steps are required.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Installing OCI8 from PECL</title>
|
|
<para xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
The OCI8 extension can be added to an existing PHP installation
|
|
either automatically or manually
|
|
from <link xlink:href="&url.pecl;">&url.pecl;</link>.
|
|
|
|
&pecl.info;
|
|
<link xlink:href="&url.pecl.package;oci8">&url.pecl.package;oci8</link>.
|
|
|
|
</para>
|
|
<para>
|
|
For an automated install follow these steps:
|
|
</para>
|
|
<para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
If you are behind a firewall, set PEAR's proxy, for example:
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
pear config-set http_proxy http://my-proxy.example.com:80/
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Run
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
pecl install oci8
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
When prompted, enter either the value of <literal>$ORACLE_HOME</literal>, or
|
|
<literal>instantclient,/path/to/instant/client/lib</literal>.
|
|
</para>
|
|
<para>
|
|
Note: Do not enter the variable <literal>$ORACLE_HOME</literal>
|
|
because it will not be expanded. Instead, enter the actual path
|
|
of the Oracle home directory.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
For a manual install, download the PECL OCI8 package,
|
|
e.g. <filename>oci8-1.3.5.tgz</filename>.
|
|
</para>
|
|
<para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Extract the package:
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
tar -zxf oci8-1.3.5.tgz
|
|
cd oci8-1.3.5
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Prepare the package:
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
phpize
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Configure the package, either
|
|
using <literal>$ORACLE_HOME</literal> or Instant Client
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
./configure -with-oci8=shared,$ORACLE_HOME
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
or
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
./configure -with-oci8=shared,instantclient,/path/to/instant/client/lib
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Install the package:
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
make install
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
After either an automatic or manual install, edit your &php.ini;
|
|
file and add the line:
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
extension=oci8.so
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
Make sure the &php.ini;
|
|
directive <link linkend="ini.extension-dir">extension_dir</link> is
|
|
set to the directory that <filename>oci8.so</filename> was installed
|
|
in.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Installing OCI8 on Windows</title>
|
|
<para>
|
|
On Windows, uncomment the &php.ini;
|
|
line <literal>extension=php_oci8.dll</literal> when using Oracle
|
|
10gR2 client libraries. Uncomment
|
|
<literal>extension=php_oci8_11g.dll</literal> when using Oracle 11g
|
|
client libraries. These two DLLs contain equivalent functionality
|
|
and only one may be enabled at a time. Make
|
|
sure <link linkend="ini.extension-dir">extension_dir</link> is set
|
|
to the directory containing the PHP extension DLLs.
|
|
</para>
|
|
<para>
|
|
If using Instant Client, set the system <literal>PATH</literal>
|
|
environment variable to the Oracle library directory.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Setting the Oracle Environment</title>
|
|
<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.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Do not set Oracle environment variables
|
|
using <function>putenv</function> in a PHP script because Oracle
|
|
libraries may be loaded and initialized before your script
|
|
runs. Variables set with <function>putenv</function> may then cause
|
|
conflicts, crashes, or unpredictable behavior. Some functions may
|
|
work but others might give subtle errors. The variables should be
|
|
set up <emphasis>before</emphasis> the web server is started.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
On Red Hat Linux and variants, export variables at the end of
|
|
<filename>/etc/sysconfig/httpd</filename>. Other systems with
|
|
Apache 2 may use an <filename>envvars</filename> script in the
|
|
Apache <filename>bin</filename> directory. A third option, the
|
|
Apache <literal>SetEnv</literal> directive
|
|
in <filename>httpd.conf</filename>, may work in some systems but is
|
|
known to be insufficient in others.
|
|
</para>
|
|
<para>
|
|
To check that environment variables are set correctly,
|
|
use <function>phpinfo</function> and check
|
|
the <emphasis>Environment</emphasis> (not the <emphasis>Apache
|
|
Environment</emphasis>) section contains the expected variables.
|
|
</para>
|
|
<para>
|
|
The variables that might be needed are included in the following
|
|
table. Refer to the Oracle documentation for more information on
|
|
all the variables.
|
|
<table>
|
|
<title>Common Oracle Environment Variables</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Name</entry>
|
|
<entry>Purpose</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>ORACLE_HOME</entry>
|
|
<entry>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.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>ORACLE_SID</entry>
|
|
<entry>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 <function>oci_connect</function>.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>LD_LIBRARY_PATH</entry>
|
|
<entry>Set this (or its platform equivalent, such
|
|
as <literal>DYLD_LIBRARY_PATH</literal>, <literal>LIBPATH</literal>,
|
|
or <literal>SHLIB_PATH</literal>) to the location of the Oracle
|
|
libraries, for example <filename>$ORACLE_HOME/lib</filename>
|
|
or <filename>/usr/lib/oracle/11.1/client/lib</filename>. This
|
|
variable is not needed if the libraries are located by a
|
|
different search mechanism, such as
|
|
with <filename>ldconfig</filename> or
|
|
with <literal>LD_PRELOAD</literal>.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>NLS_LANG</entry>
|
|
<entry>This is the primary variable for setting the character
|
|
set and globalization information used by the Oracle
|
|
libraries.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>ORA_SDTZ</entry>
|
|
<entry>Sets the Oracle session timezone.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>TNS_ADMIN</entry>
|
|
<entry>Contains the directory where the Oracle Net Services
|
|
configuration files such as <filename>tnsnames.ora</filename>
|
|
and <filename>sqlnet.ora</filename> are kept. Not needed if
|
|
the <function>oci_connect</function> connection string uses the
|
|
Easy Connect naming syntax such
|
|
as <literal>localhost/XE</literal>. Not needed if the network
|
|
configuration files are in one of the default locations such
|
|
as <filename>$ORACLE_HOME/network/admin</filename>
|
|
or <filename>/etc</filename>.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
Less frequently used Oracle environment variables include
|
|
<literal>TWO_TASK</literal>, <literal>ORA_TZFILE</literal>, and the
|
|
various Oracle globalization settings
|
|
like <literal>NLS*</literal> and the <literal>ORA_NLS_*</literal>
|
|
variables.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Troubleshooting</title>
|
|
<para>
|
|
The most common problem with installing OCI8 is not having the
|
|
Oracle environment correctly set. This typically appears as a
|
|
problem using <function>oci_connect</function>
|
|
or <function>oci_pconnect</function>. The error may be a PHP error
|
|
such as <emphasis>Call to undefined function
|
|
oci_connect()</emphasis>, 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.
|
|
</para>
|
|
<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 <filename>tnsnames.ora</filename> configuration
|
|
file.
|
|
</para>
|
|
<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.
|
|
</para>
|
|
<para>
|
|
A utility to examine what libraries are being looked for and loaded
|
|
can help resolve missing or clashing library issues, particularly on
|
|
Windows.
|
|
</para>
|
|
<note>
|
|
<title>If the web server doesn't start or crashes at
|
|
startup</title>
|
|
<para>
|
|
Check that Apache is linked with the pthread library:
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
# 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)
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
If the libpthread is not listed, then reinstall Apache:
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
# cd /usr/src/apache_1.3.xx
|
|
# make clean
|
|
# LIBS=-lpthread ./config.status
|
|
# make
|
|
# make install
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</para>
|
|
<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.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
|
|
|
|
</section> <!-- oci8.installation -->
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|
|
|