&reftitle.install;

## 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 compatibility.

## 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 options.

- 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 PHP.

- 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:

    extension=oci8.so

## Installing OCI8 as a Statically Compiled Extension

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 example:

      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 `instantclient,/path/to/instant/client/lib`.

  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:

      phpize

- Configure the package, either using `$ORACLE_HOME` or Instant Client

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

  or

      ./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:

    extension=oci8.so

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 directory.

## 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 correctly.

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 variables.

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 Variables

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 `oci_connect`.
LD_LIBRARY_PATH | Set this (or its platform equivalent, such as `DYLD_LIBRARY_PATH`, `LIBPATH`, or `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 `/etc`.

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

## Troubleshooting

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 oci_connect(), 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.

### If the web server doesn't start or crashes at startup

Check that Apache is linked with the pthread library:

    # 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 Apache:

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