If you are using Voyager or another ILS that requires an Oracle connection, you will need to install the PHP OCI Driver for Oracle. This page contains instructions on how to do this on several different platforms. First read the general notes, then skip to the section for your operating system.

Regardless of platform, you will need to download the Oracle Instant Client (at a minimum you need Basic and SDK zip files). You may need to do a Google search for the SDK; as of this writing, it is hard to find within the Oracle site. You will need to accept a license agreement and log in to Oracle's site (free account creation) in order to download the files. Be sure to select the appropriate file versions for your hardware.

Throughout this documentation, the version number 11.1 is assumed for your instantclient. If you have a newer version, you will have to remember to change all instances of 11.1 to the appropriate version (11.2, 12.1, etc.).

If you are using Voyager and running a version of VuFind® released with PHP 7 support (e.g. 8.x) under PHP 8, you will need to adjust Composer dependencies and configurations for compatibility. See the comments in Voyager.ini/VoyagerRestful.ini above the forceOCI8Support setting for details.

These instructions assume that you are logged in as the root user.

First, upgrade pear to the latest version (this won't do anything if you are already up to date).

pear upgrade pear

Create a directory to store the Oracle code and then switch to it:

mkdir -p /opt/oracle
cd /opt/oracle

Copy the instant client files (see notes above for where to find them) to the /opt/oracle directory that you just created.

Unzip the files (note that some versions of the libraries may have longer filenames - substitute as necessary):

unzip basic.zip
unzip sdk.zip

Set up some symbolic links to make the paths simpler and easier to upgrade:

ln -s instantclient_11_1 instantclient
cd /opt/oracle/instantclient
ln -s libclntsh.so.11.1 libclntsh.so
ln -s libocci.so.11.1 libocci.so

Note that numbers in some filenames may vary depending on the version you downloaded.

Set up security permissions so other code can access the libraries:

chcon -t textrel_shlib_t /opt/oracle/instantclient/*.so
execstack -c /opt/oracle/instantclient/*.so.*
setsebool -P httpd_execmem 1

Now add the Instant Client to the system dynamic library loader.

echo /opt/oracle/instantclient > /etc/ld.so.conf.d/oracle-instantclient.conf

Install some tools you will need to build libraries:

yum install gcc

Now compile and install the OCI8 package with PECL

pecl install oci8

Note, you will be prompted for the instantclient directory, so when you're prompted, just enter

instantclient,/opt/oracle/instantclient

Now install the PHP extension and restart Apache

chcon system_u:object_r:textrel_shlib_t:s0 /usr/lib/php/modules/oci8.so
chmod +x /usr/lib/php/modules/oci8.so
echo extension=oci8.so > /etc/php.d/oci8.ini
apachectl restart

This step refers to VuFind® 3.0.x and earlier; with release 3.1, the dependency on the troublesome PDO_OCI driver was removed, and you can skip ahead to step 5.

Once OCI8 is installed, you also need to set up PDO_OCI. (Notes adapted from this page).

Download and unzip the package:

mkdir -p /tmp/pear/download/
cd /tmp/pear/download/
pecl download pdo_oci
tar xvf PDO_OCI-1.0.tgz
cd PDO_OCI-1.0

Edit the config.m4 file…

Add these lines:

    elif test -f $PDO_OCI_DIR/lib/libclntsh.$SHLIB_SUFFIX_NAME.11.1; then
      PDO_OCI_VERSION=11.1    

above these lines:

    elif test -f $PDO_OCI_DIR/lib/libclntsh.$SHLIB_SUFFIX_NAME.10.1; then
      PDO_OCI_VERSION=10.1    

Also add these lines:

      11.1)
        PHP_ADD_LIBRARY(clntsh, 1, PDO_OCI_SHARED_LIBADD)
        ;;

above these lines:

      *)
        AC_MSG_ERROR(Unsupported Oracle version! $PDO_OCI_VERSION)
        ;;

If you are using PHP 5.4 or newer, you may also need to run this command:

sed -i -e 's/function_entry pdo_oci_functions/zend_function_entry pdo_oci_functions/' pdo_oci.c

Now build everything:

phpize
mkdir -p /opt/oracle/instantclient/lib/oracle/11.1
ln -s /opt/oracle/instantclient/sdk /opt/oracle/instantclient/lib/oracle/11.1/client
ln -s /opt/oracle/instantclient /opt/oracle/instantclient/lib/oracle/11.1/client/lib
./configure --with-pdo-oci=instantclient,/opt/oracle/instantclient,11.1
make
make install

Note: depending on your Instant Client version, you may need to substitute “11.1” with a different version number in the code and commands above.

Add the newly-built module to Apache's PHP configuration:

chcon system_u:object_r:textrel_shlib_t:s0 /usr/lib/php/modules/pdo_oci.so
echo extension=pdo_oci.so > /etc/php.d/pdo_oci.ini
apachectl restart

The enhanced security under Fedora can sometimes interfere with Voyager communication. If things still aren't working after you have installed the modules and connected to Voyager by editing settings in Voyager.ini, you may also need to repeat this command to unblock internal network communications:

setsebool -P httpd_can_network_relay=1

There are a few steps if you need to install the OCI8 libraries in Ubuntu.

First, upgrade pear to the latest version.

sudo pear upgrade pear

Create a directory to store the Oracle code and then switch to it:

sudo mkdir -p /opt/oracle
cd /opt/oracle

Copy the instant client files (see notes above for where to find them) to the /opt/oracle directory that you just created.

Install the unzip utility (for extracting files from the archives) if you haven't already:

sudo apt-get install unzip

Unzip the files (note that some versions of the libraries may have longer filenames - substitute as necessary):

sudo unzip basic.zip
sudo unzip sdk.zip

Set up some symbolic links to make the paths simpler and easier to upgrade:

sudo ln -s instantclient_11_1 instantclient
cd /opt/oracle/instantclient
sudo ln -s libclntsh.so.11.1 libclntsh.so
sudo ln -s libocci.so.11.1 libocci.so

Note that numbers in some filenames may vary depending on the version you downloaded.

Now add the Instant Client to the system dynamic library loader.

sudo sh -c 'echo /opt/oracle/instantclient > /etc/ld.so.conf.d/oracle-instantclient.conf'

You will need the make utility if you do not already have it. Install it like this:

sudo apt-get install make

Now compile and install the OCI8 package with PECL

sudo pecl install oci8

Note, you will be prompted for the instantclient directory, so when you're prompted, just enter

instantclient,/opt/oracle/instantclient

Now install the PHP extension and restart Apache

For Ubuntu 13.04 and earlier:

sudo sh -c 'echo extension=oci8.so > /etc/php5/apache2/conf.d/oci8.ini'
sudo /etc/init.d/apache2 restart

For Ubuntu 13.10 and later:

sudo sh -c 'echo extension=oci8.so > /etc/php5/mods-available/oci8.ini'
sudo php5enmod oci8
sudo service apache2 reload

This step refers to VuFind® 3.0.x and earlier; with release 3.1, the dependency on the troublesome PDO_OCI driver was removed, and you can skip this step.

Once OCI8 is installed, you also need to set up PDO_OCI. (Notes adapted from this page).

Install some prerequisites:

sudo apt-get install --yes build-essential libaio1

Download and unzip the package:

sudo mkdir -p /tmp/pear/download/
cd /tmp/pear/download/
sudo pecl download pdo_oci
sudo tar xvf PDO_OCI-1.0.tgz
cd PDO_OCI-1.0

Edit the config.m4 file…

Add these lines:

    elif test -f $PDO_OCI_DIR/lib/libclntsh.$SHLIB_SUFFIX_NAME.11.1; then
      PDO_OCI_VERSION=11.1    

above these lines:

    elif test -f $PDO_OCI_DIR/lib/libclntsh.$SHLIB_SUFFIX_NAME.10.1; then
      PDO_OCI_VERSION=10.1    

Also add these lines:

      11.1)
        PHP_ADD_LIBRARY(clntsh, 1, PDO_OCI_SHARED_LIBADD)
        ;;

above these lines:

      *)
        AC_MSG_ERROR(Unsupported Oracle version! $PDO_OCI_VERSION)
        ;;

If you are using PHP 5.4 or newer, you may also need to run this command:

sudo sed -i -e 's/function_entry pdo_oci_functions/zend_function_entry pdo_oci_functions/' pdo_oci.c

Now build everything:

sudo phpize
sudo mkdir -p /opt/oracle/instantclient/lib/oracle/11.1
sudo ln -s /opt/oracle/instantclient/sdk /opt/oracle/instantclient/lib/oracle/11.1/client
sudo ln -s /opt/oracle/instantclient /opt/oracle/instantclient/lib/oracle/11.1/client/lib
sudo ln -s /usr/include/php5 /usr/include/php
sudo ./configure --with-pdo-oci=instantclient,/opt/oracle/instantclient,11.1
sudo make
sudo make install

Note: depending on your Instant Client version, you may need to substitute “11.1” with a different version number in the code and commands above.

Add the newly-built module to Apache's PHP configuration:

For Ubuntu 13.04 and earlier:

sudo sh -c 'echo extension=pdo_oci.so > /etc/php5/apache2/conf.d/pdo_oci.ini'
sudo /etc/init.d/apache2 restart

For Ubuntu 13.10 and later:

sudo sh -c 'echo extension=pdo_oci.so > /etc/php5/mods-available/pdo_oci.ini'
sudo php5enmod pdo_oci
sudo service apache2 reload

PDO-OCI support is available in Windows. Just follow these steps:

1. Extract the Oracle Instant Client files from the zip archives (see above for download location) to c:\instantclient_11_1\.

2. Add the c:\instantclient_11_1\ directory to your system path as described above under the Java JDK step. Be sure you insert the Instant Client directory BEFORE any other Oracle paths in the path list.

3. Run the PHP installer and add the “Oracle (8)” and “PDO / Oracle10g Client and Above” extensions.

4. Restart Apache.

If you have trouble, try rebooting your system. If this still doesn't work, you can try upgrading to a newer version of the PHP modules – see this page.

Note: The “11_1” version number in paths above may vary depending on which file versions you download.