php-src/ext/oci8/README

Installing OCI8
---------------

0. Overview
1. Common requirements
2. Installing as a shared extension
3. Installing as a statically compiled extension
4. Installing from PECL to an existing PHP
5. Testing OCI8
6. Oracle DRCP and FAN Support


0. Overview
-----------

The OCI8 extension allows you to access Oracle databases.  It can be
built using Oracle 9.2, 10.2 or 11.1 client libraries, and allows
Oracle's standard cross-version connectivity.  This release can be
used with PHP versions 4.3.9 to 5.x.

The OCI8 extension is not related to, or used by, PDO_OCI, the PHP
Data Objects (PDO) extension for Oracle.

1. Common requirements
----------------------

This version of PHP OCI8:

  - Will build with Oracle 9.2 (or more recent) client libraries.  The
    same (or more recent) version of Oracle libraries used when
    building OCI8 must also be used at runtime.

  - Can be used with PHP versions 4.3.9 to 5.x.

If you build PHP with the "ORACLE_HOME" Oracle database or full Oracle
client libraries:

  - you MUST set at least the ORACLE_HOME environment variable and
    make it visible for your web server BEFORE it starts.

  - the Oracle software must be readable by the web server.  With
    Oracle 10.2, see the $ORACLE_HOME/install/changePerm.sh script
    included in patch releases.

If you build PHP with Oracle Instant Client libraries from
http://www.oracle.com/technology/tech/oci/instantclient/index.html

  - either the "basic" or "basic-lite" package is required.

  - the "devel" package is required.

  - you don't have to set ORACLE_HOME and many of the other
    environment variables to build PHP with OCI8 support.

For both ORACLE_HOME and Instant Client installs you may have to set:

  - LD_LIBRARY_PATH: it must include the $ORACLE_HOME/lib or Instant
    Client library directory

  - NLS_LANG: if you want to change the default encoding used during
    interaction with Oracle servers

The most appropriate places to add the environment variables are:

  /etc/profile
  /etc/profile.local
  /etc/profile.d


2. Installing as a shared extension
-----------------------------------

Configure OCI8 using one of the the following configure options:

  a) if you use an Oracle server or Oracle Client installation:

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

  b) with Oracle Instant Client:

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

    If you use an RPM-based installation of Oracle Instant Client,
    your configure line will look like this:

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

Follow the usual building procedure, e.g. "make install".  The OCI8
shared extension oci8.so 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.

Edit php.ini file and add the line:

  extension=oci8.so


3. Installing as a statically compiled extension
------------------------------------------------

Configure OCI8 using one of the the following configure options:

  a) with a common Oracle server or full Oracle client installation

      ./configure --with-oci8=$ORACLE_HOME

  b) with Oracle Instant Client

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

Run "make install".

After successful compile, you do not need to add oci8.so to php.ini.
The module will be usable without any additional actions.


4. Installing from PECL to an existing PHP
------------------------------------------

The OCI8 extension is also available as a PECL module on
http://pecl.php.net/package/oci8.

Install using either (a) or (b) below.

  a) Do an automated download and install:

    Set PEARs proxy, if necessary:

      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" (without quotes).

  b) Alternatively, manually download the PECL package, e.g. oci8-1.3.5.tgz

     Extract the package:

       tar -zxf oci8-1.3.5.tgz
       cd oci8-1.3.5

     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 install, edit your php.ini file, e.g. /etc/php.ini, and
add the line:

  extension=oci8.so

Make sure php.ini's "extension_dir" includes the directory that
oci8.so was installed in.


5. Testing OCI8
---------------

OCI8 tests are in ext/oci8/tests.  When OCI8 tests are run this
directory will contain logs of any failures.

5.1. Running OCI8 tests on Linux

5.1.1. Edit ext/oci8/tests/details.inc

  Set the username, password and connection string for the database.
  Most tests have been developed using the SYSTEM account: some tests
  might fail unless the user has permissions to create necessary
  tables, views, procedures etc.

  If the database is on the same machine as PHP, set
  $oracle_on_localhost to TRUE.

  If Oracle 11g Database Resident Connection Pooling is being tested,
  set $test_drcp to TRUE and ensure the connection string uses an
  appropriate pooled server (see section 6.2.2).

  An alternative to editing details.inc is the set the environment
  variables

    PHP_OCI8_TEST_USER
    PHP_OCI8_TEST_PASS
    PHP_OCI8_TEST_DB
    PHP_OCI8_TEST_DB_ON_LOCALHOST
    PHP_OCI8_TEST_DRCP

  for example:

    $ export PHP_OCI8_TEST_USER=system
    $ export PHP_OCI8_TEST_PASS=oracle
    $ export PHP_OCI8_TEST_DB=localhost/XE
    $ export PHP_OCI8_TEST_DB_ON_LOCALHOST=TRUE
    $ export PHP_OCI8_TEST_DRCP=FALSE

5.1.2. Set any necessary environment variables for the Oracle
    database.  With Oracle 10g XE do:

    $ . /usr/lib/oracle/xe/app/oracle/product/10.2.0/server/bin/oracle_env.sh

  For other versions of the Oracle database do:

    $ . /usr/local/bin/oraenv

5.1.3. Check your php.ini has E in the variables_order parameter, for
    example:

    variables_order = "EGPCS"

5.1.4. Run the tests:

    $ cd <your php src directory>
    $ make test TESTS=ext/oci8

5.2. The tests execute rapidly.  On fast machines with a local
  database configured for light load (e.g. Oracle 10g XE) you might
  see random tests fail with ORA-12516 or ORA-12520 errors.  To
  prevent this, increase the database PROCESSES parameter using the
  following steps.

5.2.1. Connect as the oracle software owner:

    $ su - oracle

5.2.2. Set the necessary environment variables as in 5.1.2.

5.2.3. Start the SQL*Plus command line tool and increase PROCESSES

    $ sqlplus / as sysdba
    SQL> alter system set processes=100 scope=spfile

5.2.4. Restart the database:

    SQL> startup force


6. Oracle DRCP and FAN Support
------------------------------

The PHP OCI8 extension has support for the Oracle Database Resident
Connection Pool (DRCP) and Fast Application Notification (FAN).

Questions and issues can be raised on the Oracle OTN forum (free
registration required):
http://www.oracle.com/technology/forums/php.html


6.1. Oracle Version Compatibility

The OCI8 extension will compile with Oracle libraries from version
9iR2 onwards.  However, full functionality (e.g. DRCP support) is only
available when Oracle 11g is used.

For general database functionality the version of the Oracle libraries
used by PHP does not necessarily have to match the version of the
database.


6.2. Database Resident Connection Pooling (DRCP)

DRCP allows more efficient use of database machine memory and provides
high scalability.

For DRCP to be available in OCI8, Oracle client libraries used by PHP
and the version of the Oracle Database must both be 11g.

Documentation on DRCP is found in several Oracle manuals. For example,
see "Configuring Database Resident Connection Pooling" in the Oracle
Database Administrator's Guide 11g Release 1 (11.1)
http://download.oracle.com/docs/cd/B28359_01/server.111/b28310/manproc004.htm#CHDGIDBA
for usage information.  A whitepaper
http://www.oracle.com/technology/tech/oci/pdf/oracledrcp11g.pdf
contains background information on DRCP.

After building PHP with the OCI8 extension and 11g libraries, follow
these steps:

6.2.0 Important: if Oracle Database 11.1.0.6 with DRCP connections is
    used, then the Oracle database patch for bug 6474441 must be
    applied (see section 6.5).  Without this patch, "ORA-01000:
    maximum open cursors exceeded", "ORA-01001 invalid cursor" or
    "ORA-01002 fetch out of sequence" errors may occur.

    If the Oracle 11.1.0.6 database patch cannot be applied, one of
    the following three workarounds can be used to disable statement
    caching instead:

    (i) Connect using Oracle dedicated or shared servers instead of DRCP.

    (ii) Set PHP's oci8.statement_cache_size to 0.

    (iii) Set an event in the database initialization parameter file:
    event="56699 trace name context forever, level 128".


6.2.1. As a privileged database administrator, use a program like
       SQL*Plus to start the connection pool in the database:

        SQL> execute dbms_connection_pool.start_pool;

     Optional settings control the size and characteristics of the
     pool.

6.2.2. For PHP applications that currently connect using a Network Alias
       like:

          $c = oci_pconnect("myuser", "mypassword", "MYDB");

       Modify your tnsnames.ora file and add the "(SERVER=POOLED)"
       clause, for example:

          MYDB = (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp) (HOST=myhost.dom.com)
                 (PORT=1521))(CONNECT_DATA=(SERVICE_NAME=sales)
                 (SERVER=POOLED)))

     Alternatively, modify the Easy Connect syntax in PHP and add
     ":POOLED" after the service name:

          $c = oci_pconnect("myuser", "mypassword",
                            "myhost.dom.com:1521/sales:POOLED");

6.2.3. Edit php.ini and choose a connection class name.  This name
       indicates a logical division of the connection pool and can be
       used to isolate pooling for separate applications.  Any PHP
       instance with the same connection class value will share
       connections in the pool.

          oci8.connection_class = "MY_APPLICATION_NAME"

6.2.4. Run your application, connecting to the 11g database.


6.3. Fast Application Notification (FAN) Support

FAN support gives fast connection failover, a high availability
feature.  This allows PHP OCI8 scripts to be notified when a database
machine or database instance becomes unavailable.  Without FAN, OCI8
can hang until a TCP timeout occurs and an error is returned, which
might be several minutes.  Enabling FAN in OCI8 can allow your
applications to detect errors and re-connect to an available database
instance without the web user being aware of an outage.

FAN support is available when the Oracle client libraries that PHP
links with and the Oracle Database are either version 10gR2 or 11g.

FAN benefits users of Oracle's clustering technology (RAC) because
connections to surviving database instances can be immediately made.
Users of Oracle's Data Guard with a broker will see the FAN events
generated when the standby database goes online.  Standalone databases
will send FAN events when the database restarts.

For active connections, when a machine or database instance becomes
unavailable, a connection failure error will be returned by the OCI8
extension function currently being called.  On a subsequent PHP script
re-connect, a connection to a surviving database instance will be
established.  The OCI8 extension also transparently cleans up any idle
connections affected by a database machine or instance failure so PHP
connect calls will establish a fresh connection without the script
being aware of any service disruption.

When oci8.events is On, it is suggested to set oci8.ping_interval to
-1 to disable pinging, since enabling FAN events provide pro-active
connection management of idle connections made invalid by a service
disruption.

To enable FAN support in PHP, after building PHP with Oracle 10gR2 or
11g libraries follow these steps:

6.3.1. As a privileged database administrator, use a program like
       SQL*Plus to enable the database service to post FAN events, for
       example:

          SQL> execute dbms_service.modify_service(
                 SERVICE_NAME        => 'sales',
                 AQ_HA_NOTIFICATIONS => TRUE);

6.3.2. Edit php.ini and add

          oci8.events = On

6.3.3. If your application does not already handle OCI8 error
       conditions, modify it to detect failures and take appropriate
       action.  This may include re-connecting and re-executing
       statements.

6.3.4. Run your application, connecting to a 10gR2 or 11g database.


6.4. Recommendations and Known Limitations

6.4.1 Changing Password for DRCP connections

Changing a password over DRCP connections will fail with the error
"ORA-56609: Usage not supported with DRCP".  This is an documented
restriction of Oracle Database 11g.

6.4.2 Closing Connections

With the PHP OCI8 extension, persistent connections can now be closed
by the user, allowing greater control over connection resource usage.
Persistent connections will now also be closed automatically when
there is no PHP variable referencing them, such as at the end of scope
of a PHP user function.  This will rollback any uncommitted
transaction.  These changes to persistent connections make them behave
similarly to non-persistent connections, simplifying the interface,
allowing for greater application consistency and predictability.  Use
oci8.old_oci_close_semantics=1 to retain the historical behavior.

6.4.3 LOGON Triggers can be used to set session properties

The patch for Oracle Database 11.1.0.6 bug 6474441 (see section 6.5)
allows PHP applications with DRCP connection to use a database LOGON
trigger to set session properties at the time of session creation.
Examples of such settings are the NLS language and the date format.

If the Oracle 11.1.0.6 database patch cannot be applied, one of the
following workarounds can be used:

(i) After logon, explicitly set the session properties using PHP
application code.

(ii) Connect using Oracle dedicated or shared servers instead of DRCP.

With DRCP there is an connection management relationship between (i)
DRCP's automatic pool expansion and reduction, (ii) PHP's persistent
connection caching, (iii) with the way LOGON triggers fire with DRCP
authentication.  Because of this interplay, LOGON triggers in PHP
(when DRCP is used) are only recommended for setting session
attributes and not for per-PHP connection events.


6.5. Patching Oracle Database 11g

The patch for bug 6474441 is available from Oracle Support's Metalink
system.

The bug is specific to Oracle 11.1.0.6 with DRCP connections.  The
issues it fixes do not affect connections using Oracle's dedicated
(the default connection mode) or shared servers.  They do not affect
earlier versions of Oracle.  The bug is intended to be fixed in Oracle
Database 11.1.0.7 (as yet unreleased).