Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Branch: experimental/5…
Pull request Compare This branch is 4 commits ahead, 55363 commits behind master.

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


Installing OCI8

1. Common requirements.
2. Installing as shared extension.
3. Installing as statically compiled extension.
4. Installing from PECL.
5. Testing OCI8
6. DRCP and FAN Support

1. Common requirements

If you use a common Oracle Client installation that comes with the
Oracle server installation, you MUST set at least the ORACLE_HOME
environment variable and make it visible for your web-server BEFORE it

If you use Oracle Instant Client, you don't have to set ORACLE_HOME
and many of the other environment variables to build PHP with OCI8
support.  The only variables you may have to set are:

  LD_LIBRARY_PATH - it must include the 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:


2. Installing as shared extension

To install OCI8 as a shared extension (i.e. the one you should put
into your php.ini) use the following configure lines to configure PHP:

a) if you use a common Oracle 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/<OIC version>/client/lib

Follow the usual building procedure after that and you'll get an OCI8
shared extension (i.e. Add it into the php.ini file like

and don't forget to specify the right extension_dir for PHP to be able
to find shared extensions correctly.

3. Installing as statically compiled extension

To install OCI8 as statically compiled module use the following
configure lines:

a) with a common Oracle or Oracle Client installation

  ./configure --with-oci8=$ORACLE_HOME

b) with Oracle Instant Client

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

After successful compile, you don't have to add to the
php.ini.  The module will be usable without any additional actions.

4. Installing from PECL


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/

  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.

  An alternative to editing is the set the environment


  for example:

    $ export PHP_OCI8_TEST_USER=system
    $ export PHP_OCI8_TEST_PASS=oracle
    $ export PHP_OCI8_TEST_DB=localhost/XE

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/

  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

    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

5.2.5. Rerun the tests

6. DRCP and FAN Support

Th PHP OCI8 1.3.0 Beta extension has support for the Oracle Database
Resident Connection Pool (DRCP) and Fast Application Notification

OCI8 1.3.0 Beta is for Beta testing only.  Questions and issues can be
raised on the Oracle OTN forum (free registration required)

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 other, 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)
for usage information.  A whitepaper
contains background information on DRCP.

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

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

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

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

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


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

          $c = oci_pconnect("myuser", "mypassword", 

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

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

	  SQL> execute dbms_service.modify_service(
		 SERVICE_NAME        => 'sales',

6.3.2. Edit php.ini and add

 = 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

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

6.4. Changes and Known Issues in OCI8 1.3.0 Beta

6.4.1. Oci8.max_persistent

The parameter oci8.max_persistent is no longer used.  DRCP users
should modify the connection pool settings of the database to control
resource usage.  Non-DRCP users should consider setting
oci8.persistent_timeout to a non -1 value to close idle connections.

6.4.2. Password changing

When oci_password_change() is successfully performed in a PHP script,
subsequent connections with the new password from this PHP instance
will fail with "ORA-1017 invalid username/password".  Subsequent
connections in a new PHP instance (e.g. CLI process, or restarted web
server) will connect successfully.

6.4.3 Statement Caching

Statement caching is currently disabled in this release, OCI8 1.3.0 Beta.
Something went wrong with that request. Please try again.