-Installing OCI8
----------------
+The OCI8 Extension
+------------------
-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
+The OCI8 extension allows PHP to access Oracle databases. It can be
+built using Oracle 9.2, 10, or 11 client libraries. It allows Oracle's
+standard cross-version connectivity, for example PHP using Oracle 10.2
+libraries can connect to Oracle Database 9.2 onwards.
+This release of OCI8 can be used with PHP versions 4.3.9 to 5.x.
-0. Overview
------------
-
-The OCI8 extension allows you to access Oracle databases. It can be
-built using Oracle 9.2, 10.2, 11.1 or 11.2 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 fixed in Oracle Database
-11.1.0.7.
+OCI8 installation instructions and documentation is available at
+http://www.php.net/oci8
projects / php / commitdiff