• Installing/Configuring
  • Installation

  • Installation
  • Installation


    Configuring PHP with OCI8

    Review the previous Requirements section
    before configuring OCI8.

    To enable the OCI8 extension, configure PHP with
    the option –with-oci8

    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 before any PHP
    process starts.

    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

    Installing OCI8 as a Shared Extension

    The configuration shared 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.

    Configure OCI8 using one of the following configure

    • If using the free » Oracle Instant Client
      libraries, then do:

      ./configure --with-oci8=shared,instantclient,/path/to/instant/client/lib

      If Instant Client is installed from ZIP files, make
      sure to create the library symbolic link first, for example ln
      -s libclntsh.so.12.1 libclntsh.so

      If using an RPM-based installation of Oracle
      Instant Client, the configure line will look like this:

      ./configure --with-oci8=shared,instantclient,/usr/lib/oracle/<version>/client/lib

      For example, –with-oci8=shared,instantclient,/usr/lib/oracle/12.1/client/lib

      Note that Oracle Instant Client support first
      appeared in PHP 4.3.11 and 5.0.4 and originally used the option
      –with-oci8-instant-client to configure

    • If using an Oracle database or full Oracle Client
      installation then do:

      ./configure --with-oci8=shared,$ORACLE_HOME

      Make sure the web server user (nobody,
      www) has access to the libraries, initialization files and
      tnsnames.ora (if used) under the
      $ORACLE_HOME directory. With Oracle 10gR2, you may need to run the $ORACLE_HOME/install/changePerm.sh utility to give
      directory access.

    After configuration, follow the usual PHP building
    procedure, e.g. make install. The OCI8
    shared extension oci8.so library will
    be created. It may need to be manually moved to the PHP extension
    directory, specified by the extension_dir
    option in your php.ini file.

    To complete installation of OCI8, edit php.ini and add the line:


    Installing OCI8 as a Statically Compiled

    Configure PHP to include OCI8 using one of the
    following configure options.

    • If using Oracle Instant Client, then do:

      ./configure --with-oci8=instantclient,/path/to/instant/client/lib
    • If using an Oracle database or full Oracle Client
      installation then do:

      ./configure --with-oci8=$ORACLE_HOME

    After configuration, follow the usual PHP building
    procedure, e.g. make install. After
    successful compilation, you do not need to add oci8.so to php.ini. No
    additional build steps are required.

    Installing OCI8 from PECL

    The OCI8 extension can be added to an existing PHP
    installation either automatically or manually from » PECL.

    For an automated install follow these steps:

    • If you are behind a firewall, set PEAR’s proxy, for

      pear config-set http_proxy http://my-proxy.example.com:80/
    • Run

      pecl install oci8

      When prompted, enter either the value of
      $ORACLE_HOME, or

      Note: Do not enter the variable
      $ORACLE_HOME because it will not be expanded. Instead,
      enter the actual path of the Oracle home directory.

    For a manual install when the pecl command
    is not available, download the PECL OCI8 package, e.g. oci8-1.4.10.tgz.

    • Extract the package:

      tar -zxf oci8-1.4.10.tgz
      cd oci8-1.4.10
    • Prepare the package:

    • Configure the package, either using
      $ORACLE_HOME or Instant Client

      ./configure -with-oci8=shared,$ORACLE_HOME


      ./configure -with-oci8=shared,instantclient,/path/to/instant/client/lib
    • Install the package:

      make install

    After either an automatic or manual install, edit
    your php.ini file and add the line:


    Make sure the php.ini
    directive extension_dir is set to the directory that oci8.so was installed in.

    Installing OCI8 on Windows

    When using Oracle 10gR2
    client libraries on Windows, uncomment the php.ini line extension=php_oci8.dll. When
    using Oracle 11gR2 or later client
    libraries, uncomment extension=php_oci8_11g.dll or
    extension=php_oci8.dll. With Oracle 12c libraries use extension=php_oci8_12c.dll
    or extension=php_oci8_11g.dll or
    extension=php_oci8.dll. 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 extension_dir is set to the directory containing the PHP
    extension DLLs.

    If using Instant Client, set the system PATH environment variable to the Oracle library

    Setting the Oracle Environment

    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


    Do not set Oracle environment variables using
    putenv() in a PHP script because Oracle
    libraries may be loaded and initialized before your script runs.
    Variables set with putenv() may
    then cause conflicts, crashes, or unpredictable behavior. Some
    functions may work but others might give subtle errors. The
    variables should be set up before the web
    server is started.

    On Red Hat Linux and variants, export variables at
    the end of /etc/sysconfig/httpd. Other
    systems with Apache 2 may use an envvars script in the Apache bin directory. A third option, the Apache
    SetEnv directive in httpd.conf, may work in some systems but is known
    to be insufficient in others.

    To check that environment variables are set
    correctly, use phpinfo() and
    check the Environment (not the Apache Environment) section contains the expected

    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.

    Common Oracle Environment
    Name Purpose
    ORACLE_HOME 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.
    ORACLE_SID 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
    LD_LIBRARY_PATH Set this (or its platform equivalent, such as
    SHLIB_PATH) to the location of the Oracle libraries, for
    example $ORACLE_HOME/lib or /usr/lib/oracle/11.1/client/lib. This variable is
    not needed if the libraries are located by a different search
    mechanism, such as with ldconfig or
    with LD_PRELOAD.
    NLS_LANG This is the primary variable for setting the character set and
    globalization information used by the Oracle libraries.
    ORA_SDTZ Sets the Oracle session timezone.
    TNS_ADMIN Contains the directory where the Oracle Net Services
    configuration files such as tnsnames.ora and sqlnet.ora are kept. Not needed if the
    oci_connect() connection string uses the Easy
    Connect naming syntax such as localhost/XE. Not needed if
    the network configuration files are in one of the default locations
    such as $ORACLE_HOME/network/admin or

    Less frequently used Oracle environment variables include
    TWO_TASK, ORA_TZFILE, and the various Oracle
    globalization settings like NLS* and the
    ORA_NLS_* variables.


    The most common problem with installing OCI8 is not
    having the Oracle environment correctly set. This typically appears
    as a problem using oci_connect() or oci_pconnect(). The error may be a PHP error
    such as Call to undefined function
    , 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.

    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 tnsnames.ora configuration file.

    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.

    A utility to examine what libraries are being
    looked for and loaded can help resolve missing or clashing library
    issues, particularly on Windows.

    Note: If the web server
    doesn’t start or crashes at startup

    Check that Apache is linked with the pthread

    # 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)

    If the libpthread is not listed, then reinstall

    # cd /usr/src/apache_1.3.xx
    # make clean
    # LIBS=-lpthread ./config.status
    # make
    # make install

    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.