<?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>
   </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
-->