====== PHP OCI Driver for Oracle ======

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.

===== General Notes =====

==== Getting Started ====

Regardless of platform, you will need to download the [[http://www.oracle.com/technetwork/database/features/instant-client/index-097480.html|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.

==== IMPORTANT ====

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

==== PHP 8 NOTE ====

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.
===== Fedora =====

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

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

<code bash>
pear upgrade pear
</code>

==== 2. Extract the Oracle Instant Client ====

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

<code bash>
mkdir -p /opt/oracle
cd /opt/oracle
</code>

Copy the instant client files (see [[#General_Notes|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):

<code bash>
unzip basic.zip
unzip sdk.zip
</code>

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

<code bash>
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
</code>

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

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

==== 3. Install the Client and PHP Extension ====

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

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

Install some tools you will need to build libraries:

<code bash>
yum install gcc
</code>

Now compile and install the OCI8 package with PECL 

<code bash>
pecl install oci8
</code>

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

<code bash>
instantclient,/opt/oracle/instantclient
</code>

Now install the PHP extension and restart Apache

<code bash>
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
</code>


==== 4. Set up PDO_OCI ====

:!: // 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 [[http://ubuntuforums.org/showthread.php?p=7581997|this page]]).

Download and unzip the package:

<code bash>
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
</code>

Edit the config.m4 file...

Add these lines:

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

above these lines:

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

Also add these lines:

<code>
      11.1)
        PHP_ADD_LIBRARY(clntsh, 1, PDO_OCI_SHARED_LIBADD)
        ;;
</code>

above these lines:

<code>
      *)
        AC_MSG_ERROR(Unsupported Oracle version! $PDO_OCI_VERSION)
        ;;
</code>

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

<code bash>
sed -i -e 's/function_entry pdo_oci_functions/zend_function_entry pdo_oci_functions/' pdo_oci.c
</code>

Now build everything:

<code bash>
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
</code>

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

<code bash>
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
</code>

==== 5. Reaffirm Security Settings ====

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:

<code bash>
setsebool -P httpd_can_network_relay=1
</code>

===== Ubuntu =====

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

==== 1. Upgrade PEAR ====
First, upgrade pear to the latest version.

<code bash>
sudo pear upgrade pear
</code>

==== 2. Download and Extract the Oracle Instant Client ====

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

<code bash>
sudo mkdir -p /opt/oracle
cd /opt/oracle
</code>

Copy the instant client files (see [[#General_Notes|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:

<code bash>
sudo apt-get install unzip
</code>

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

<code bash>
sudo unzip basic.zip
sudo unzip sdk.zip
</code>

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

<code bash>
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
</code>

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


==== 3. Install the Client and PHP Extension ====

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

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

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

<code bash>
sudo apt-get install make
</code>

Now compile and install the OCI8 package with PECL 

<code bash>
sudo pecl install oci8
</code>

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

<code bash>
instantclient,/opt/oracle/instantclient
</code>

Now install the PHP extension and restart Apache

// For Ubuntu 13.04 and earlier: //

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

// For Ubuntu 13.10 and later: //

<code bash>
sudo sh -c 'echo extension=oci8.so > /etc/php5/mods-available/oci8.ini'
sudo php5enmod oci8
sudo service apache2 reload
</code>
==== 4. Set up PDO_OCI ====

:!: // 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 [[http://ubuntuforums.org/showthread.php?p=7581997|this page]]).

Install some prerequisites:

<code bash>
sudo apt-get install --yes build-essential libaio1
</code>

Download and unzip the package:

<code bash>
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
</code>

Edit the config.m4 file...

Add these lines:

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

above these lines:

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

Also add these lines:

<code>
      11.1)
        PHP_ADD_LIBRARY(clntsh, 1, PDO_OCI_SHARED_LIBADD)
        ;;
</code>

above these lines:

<code>
      *)
        AC_MSG_ERROR(Unsupported Oracle version! $PDO_OCI_VERSION)
        ;;
</code>

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

<code bash>
sudo sed -i -e 's/function_entry pdo_oci_functions/zend_function_entry pdo_oci_functions/' pdo_oci.c
</code>

Now build everything:

<code bash>
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
</code>

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

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

// For Ubuntu 13.10 and later: //

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

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

1. Extract the Oracle Instant Client files from the zip archives ([[#General_Notes|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 [[legacy:installation:windows#install_the_java_jdk|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 [[http://www.oracle.com/technology/pub/notes/technote_php_instant.html|this page]].

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