mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-20 19:08:54 +00:00
8b3444158b
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@351756 c90b9560-bf6c-de11-be94-00142212c4b1
618 lines
18 KiB
XML
618 lines
18 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>
|
|
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
|
|
<emphasis>before</emphasis> any PHP process starts.
|
|
</para>
|
|
<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 19 libraries, then PHP should also be deployed
|
|
and run with Oracle 19 libraries. PHP applications can connect to other
|
|
versions of Oracle Database, since Oracle has client-server cross-version compatibility.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Installing OCI8 from PECL Using the pecl Command</title>
|
|
<para xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
The OCI8 extension can be added to an existing PHP installation by using
|
|
the <link xlink:href="&url.pecl.package;oci8">PECL</link> repository.
|
|
</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>
|
|
For PHP 7, use <literal>pecl install oci8-2.2.0</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<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 variable names like <literal>$ORACLE_HOME</literal>
|
|
or <literal>$HOME</literal> because <literal>pecl</literal> will not
|
|
expand them. Instead, enter an expanded path, for
|
|
example <literal>/opt/oracle/product/19c/dbhome_1</literal>
|
|
or <literal>instantclient,/Users/myname/Downloads/instantclient_19_8</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If you get an error <literal>oci8_dtrace_gen.h: No such file or
|
|
directory</literal>, it means PHP was built
|
|
with <link linkend="features.dtrace">DTrace Dynamic Tracing</link> enabled.
|
|
Install using:
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
$ export PHP_DTRACE=yes
|
|
$ pecl install oci8
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
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>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Installing OCI8 from PECL Using phpize</title>
|
|
<para xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
To install OCI8 on an existing PHP installation when
|
|
the <literal>pecl</literal> command is not available, manually download
|
|
the <link xlink:href="&url.pecl.package;oci8">PECL</link> OCI8 package,
|
|
e.g. <filename>oci8-3.0.0.tgz</filename>.
|
|
</para>
|
|
<para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Extract the package:
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
tar -zxf oci8-3.0.0.tgz
|
|
cd oci8-3.0.0
|
|
]]>
|
|
</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>
|
|
<listitem>
|
|
<para>
|
|
If you get an error <literal>oci8_dtrace_gen.h: No such file or
|
|
directory</literal>, it means PHP was built
|
|
with <link linkend="features.dtrace">DTrace Dynamic Tracing</link> enabled.
|
|
Re-run the <literal>configure</literal> and <literal>make</literal>
|
|
commands after setting this environment variable:
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
$ export PHP_DTRACE=yes
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
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>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Installing OCI8 as a Shared Extension when Building PHP</title>
|
|
<para>
|
|
If you are building PHP from source code, the
|
|
configuration <literal>shared</literal> option can be used to build 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 the free <link xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
xlink:href="&url.oracle.instant.client;">Oracle Instant
|
|
Client</link> libraries, then do:
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
./configure --with-oci8=shared,instantclient,/path/to/instant/client/lib
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
If Instant Client 12.2 (or earlier) is installed from ZIP files, make sure to create
|
|
the library symbolic link first, for example <literal>ln -s
|
|
libclntsh.so.12.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/19.9/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
|
|
10<emphasis>g</emphasis>R2, 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 when Building PHP</title>
|
|
<para>
|
|
If you are building PHP from source code, you can configure PHP to include
|
|
OCI8 as a static extension 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 on Windows</title>
|
|
<para xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
The OCI8 extension can be added to an existing PHP installation by using the
|
|
DLLs from <link xlink:href="&url.pecl.package;oci8">PECL</link> repository or
|
|
the libraries in your PHP installation's <literal>ext</literal> directory.
|
|
</para>
|
|
<para>
|
|
With Oracle 12<emphasis>c</emphasis> (or later) libraries, uncomment one of
|
|
the &php.ini; lines <literal>extension=php_oci8_12c.dll</literal>
|
|
or <literal>extension=php_oci8_11g.dll</literal>
|
|
or <literal>extension=php_oci8.dll</literal>. 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 <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 <envar>PATH</envar>
|
|
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 available 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>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/18.5/client/lib</filename>. Note with Instant
|
|
Client ZIP files on Linux it is more reliable to
|
|
use <filename>ldconfig</filename> instead, see the Instant Client
|
|
installation instructions. With Instant Client 19 (or later) RPM
|
|
files, <literal>ldconfig</literal> is automatically run for you. Some
|
|
users use
|
|
<literal>LD_PRELOAD</literal> instead
|
|
of <literal>LD_LIBRARY_PATH</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>/usr/lib/oracle/VERSION/client/lib/network/admin</filename>, <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
|
|
-->
|
|
|