Installation
Installing OCI8 from PECL Using the pecl Command
The OCI8 extension can be added to an existing PHP installation by using
the » PECL repository.
-
If you are behind a firewall, set PEAR's proxy, for example:
-
Run
For PHP 7, use pecl install oci8-2.2.0
-
When prompted, enter either the value of $ORACLE_HOME
, or
instantclient,/path/to/instant/client/lib
.
Note: Do not enter variable names like $ORACLE_HOME
or $HOME
because pecl
will not
expand them. Instead, enter an expanded path, for
example /opt/oracle/product/19c/dbhome_1
or instantclient,/Users/myname/Downloads/instantclient_19_8
-
If you get an error oci8_dtrace_gen.h: No such file or
directory
, it means PHP was built
with DTrace Dynamic Tracing enabled.
Install using:
-
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 from PECL Using phpize
To install OCI8 on an existing PHP installation when
the pecl
command is not available, manually download
the » PECL OCI8 package,
e.g. oci8-3.0.0.tgz.
-
Extract the package:
-
Prepare the package:
-
Configure the package, either
using $ORACLE_HOME
or Instant Client
or
-
Install the package:
-
If you get an error oci8_dtrace_gen.h: No such file or
directory
, it means PHP was built
with DTrace Dynamic Tracing enabled.
Re-run the configure
and make
commands after setting this environment variable:
-
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 as a Shared Extension when Building PHP
If you are building PHP from source code, the
configuration shared
option can be used to build 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:
If Instant Client 12.2 (or earlier) 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:
For example, --with-oci8=shared,instantclient,/usr/lib/oracle/19.9/client/lib
-
If using an Oracle database or full Oracle Client installation then do:
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 Extension when Building PHP
If you are building PHP from source code, you can configure PHP to include
OCI8 as a static extension using one of the following configure options.
-
If using Oracle Instant Client, then do:
-
If using an Oracle database or full Oracle Client installation then do:
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 on Windows
The OCI8 extension can be added to an existing PHP installation by using the
DLLs from » PECL repository or
the libraries in your PHP installation's ext
directory.
With Oracle 12c (or later) libraries, uncomment one of
the php.ini lines 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.
Note:
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 LIBPATH , or SHLIB_PATH ) to the
location of the Oracle libraries, for
example $ORACLE_HOME/lib
or /usr/lib/oracle/18.5/client/lib. Note with Instant
Client ZIP files on Linux it is more reliable to
use ldconfig instead, see the Instant Client
installation instructions. With Instant Client 19 (or later) RPM
files, ldconfig is automatically run for you. Some
users use
LD_PRELOAD instead
of LD_LIBRARY_PATH . |
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 /usr/lib/oracle/VERSION/client/lib/network/admin, $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.
Note:
If the web server doesn't start or crashes at
startup
Check that Apache is linked with the pthread library:
If the libpthread is not listed, then reinstall Apache:
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.