Configuration de PHP avec OCI8

Consulter la section précédente sur les Pré-requis avant de configurer OCI8.

Avant de démarrer le serveur web, OCI8, typiquement, nécessite plusieurs variables d'environnement (voir ci-dessous) pour localiser les bibliothèques, pour pointer vers des fichiers de configuration, et pour définir quelques propriétés basiques comme le jeu de caractères utilisé par les bibliothèques OCI8. Les variables doivent être définies avant le démarrage d'un quelconque processus PHP.

Le binaire PHP doit être lié avec les mêmes (ou plus récentes) versions majeures des bibliothèques Oracle pour lesquelles il a été configuré. Par exemple, si on compile OCI8 avec les bibliothèques Oracle 19, alors PHP doit aussi être déployé et exécuté avec les bibliothèques Oracle 19. Les applications PHP peuvent se connecter à d'autres versions de base de données Oracle, sachant qu'Oracle contient des compatibilités de versions des différents clients - serveurs.

Installation d'OCI8 depuis PECL en utilisant la commande pecl

L'extension OCI8 peut être ajoutée à une installation PHP existante en utilisant le référentiel » PECL.

Si on est derrière un pare-feu, définissez le proxy de PEAR, par exemple :
```
pear config-set http_proxy http://my-proxy.example.com:80/
```
Exécuter :
```
pecl install oci8
```
Pour PHP 7, utiliser pecl install oci8-2.2.0.
Lorsqu'on le demande, saisissez la valeur de $ORACLE_HOME ou instantclient,/chemin/vers/le/répertoire/instant/client/lib.

Remarque : Ne saisissez pas de noms de variables tels que $ORACLE_HOME ou $HOME car pecl ne les développera pas. Au lieu de cela, saisissez un chemin développé, par exemple /opt/oracle/product/19c/dbhome_1 ou instantclient,/Users/monnom/Téléchargements/instantclient_19_8.
Si on obtient une erreur oci8_dtrace_gen.h: Aucun fichier ou répertoire de ce type, cela signifie que PHP a été compilé avec DTrace Dynamic Tracing activé. Installer en utilisant la commande :
```
$ export PHP_DTRACE=yes
$ pecl install oci8
```
Modifier le fichier php.ini et ajouter la ligne :
```
extension=oci8.so
```
Il faut s'assurer que la directive php.ini extension_dir est définie sur le répertoire dans lequel oci8.so a été installé.

Installation d'OCI8 depuis PECL en utilisant phpize

Pour installer OCI8 sur une installation PHP existante lorsque la commande pecl n'est pas disponible, téléchargez manuellement le package OCI8 » PECL, par exemple oci8-3.0.0.tgz.

Extraire le package :
```
tar -zxf oci8-3.0.0.tgz
cd oci8-3.0.0
```
Préparer le package :
```
phpize
```

Configurer le package en utilisant soit $ORACLE_HOME, soit Instant Client.

./configure -with-oci8=shared,$ORACLE_HOME

ou

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

Installer le package :
```
make install
```
Si on obtient une erreur oci8_dtrace_gen.h: Aucun fichier ou répertoire de ce type, cela signifie que PHP a été compilé avec DTrace Dynamic Tracing activé. Exécuter à nouveau les commandes configure et make après avoir défini cette variable d'environnement :
```
$ export PHP_DTRACE=yes
```
Modifier le fichier php.ini et ajouter la ligne :
```
extension=oci8.so
```
Il faut s'assurer que la directive php.ini extension_dir est configurée sur le répertoire dans lequel oci8.so a été installé.

Installation d'OCI8 en tant qu'extension partagée lors de la compilation de PHP

Si on compile PHP à partir du code source, l'option de configuration shared peut être utilisée pour construire OCI8 en tant que bibliothèque partagée qui peut être chargée dynamiquement dans PHP. La construction d'une extension partagée permet à OCI8 d'être facilement mis à jour sans avoir d'impact sur le reste de PHP.

Configurer OCI8 en utilisant l'une des options de configuration suivantes.

Lors de l'utilisation des bibliothèques gratuites » Oracle Instant Client, faites ce qui suit :
```
./configure --with-oci8=shared,instantclient,/path/to/instant/client/lib
```
Si Instant Client 12.2 (ou une version antérieure) est installé à partir de fichiers ZIP, il faut s'assurer de créer d'abord le lien symbolique vers la bibliothèque, par exemple ln -s libclntsh.so.12.1 libclntsh.so.

Lors de l'utilisation d'une installation basée sur RPM d'Oracle Instant Client, la ligne de configuration ressemblera à ceci :
```
./configure --with-oci8=shared,instantclient,/usr/lib/oracle/<version>/client/lib
```
Par exemple, --with-oci8=shared,instantclient,/usr/lib/oracle/19.9/client/lib
Lors de l'utilisation d'une base de données Oracle ou une installation complète d'Oracle Client, procédez comme suit :
```
./configure --with-oci8=shared,$ORACLE_HOME
```
Il faut s'assurer que l'utilisateur du serveur web (nobody, www) a accès aux bibliothèques, aux fichiers d'initialisation et au fichier tnsnames.ora (si utilisé) sous le répertoire $ORACLE_HOME. Avec Oracle 10gR2, il faudra peut-être exécuter l'utilitaire $ORACLE_HOME/install/changePerm.sh pour donner accès au répertoire.

Après la configuration, suivez la procédure habituelle de compilation de PHP, par exemple make install. L'extension partagée OCI8 oci8.so sera créée. Il peut être nécessaire de la déplacer manuellement dans le répertoire des extensions PHP, spécifié par l'option extension_dir dans le fichier php.ini.

Pour terminer l'installation d'OCI8, modifiez le fichier php.ini et ajoutez la ligne :

extension=oci8.so

Installation d'OCI8 en tant qu'extension statiquement compilée lors de la compilation de PHP

Si on compile PHP à partir du code source, il est possible de configurer PHP pour inclure OCI8 en tant qu'extension statique en utilisant l'une des options de configuration suivantes.

Lors de l'utilisation d'Oracle Instant Client, faites ce qui suit :

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

Lors de l'utilisation d'une base de données Oracle ou une installation complète du client Oracle, faites ce qui suit :
```
./configure --with-oci8=$ORACLE_HOME
```

Après la configuration, suivez la procédure habituelle de construction de PHP, par exemple make install. Après une compilation réussie, il n'est pas nécessaire d'ajouter oci8.so au php.ini. Aucune étape supplémentaire de construction n'est requise.

Installation d'OCI8 sous Windows

La bibliothèque OCI8 peut être ajoutée à une installation existante de PHP en utilisant les DLL du référentiel » PECL ou les bibliothèques situées dans le répertoire ext de l'installation PHP.

Avec les bibliothèques Oracle 12c (ou ultérieures), décommentez l'une des lignes suivantes dans le fichier php.ini extension=php_oci8_12c.dll ou extension=php_oci8_11g.dll, ou bien extension=php_oci8.dll. Seule une de ces DLL doit être active au même moment. Les DLLs avec des versions supérieures peuvent contenir plus de fonctionnalités. Toutes les DLLs peuvent ne pas être disponibles pour toutes les versions de PHP. Il faut s'assurer que l'option extension_dir est définie sur le dossier contenant les extensions DLLs de PHP.

Lors de l'utilisation du client Oracle Instant, définissez la variable d'environnement PATH du système au dossier contenant les bibliothèques Oracle.

Définition de l'environnement Oracle

Avant d'utiliser cette extension, il faut s'assurer que les variables d'environnement Oracle sont correctement définies pour l'utilisateur exécutant le serveur Web. Si le serveur Web est automatiquement démarré au démarrage du serveur, alors il faut s'assurer également de la bonne configuration de la variable d'environnement utilisée à ce moment-ci.

Note:
Ne définissez pas les variables d'environnement Oracle en utilisant la fonction putenv() dans les scripts PHP, car les bibliothèques Oracle sont chargées et initialisées avant l'exécution du script. Les variables définies avec putenv() pourraient ainsi entrer en conflit et provoquer aussi bien des crashs que des comportements totalement inattendus. Des fonctions peuvent réagir normalement, d'autres peuvent provoquer des erreurs. Les variables doivent être définies avant le démarrage du serveur.

Sous les systèmes Red Hat Linux et ces variantes, il faut exporter les variables à la fin du fichier /etc/sysconfig/httpd. Sous les autres systèmes utilisant Apache 2, il faut utiliser le script envvars qu'on trouvera dans le dossier bin d'Apache. Une autre option consiste à utiliser la directive SetEnv du fichier httpd.conf, mais ceci peut ne pas être suffisant sur quelques systèmes.

Pour vérifier si les variables d'environnement ont été définies correctement, utiliser la fonction phpinfo() et s'attarder sur la section Environment (et non la section Apache Environment) ; elle doit contenir toutes les variables définies.

Les variables qui pourraient être nécessaires sont incluses dans le tableau suivant. Se reporter à la documentation Oracle pour plus d'informations sur toutes les variables.
Variables d'environnement Oracle communes

Nom But

ORACLE_HOME Chemin vers le dossier contenant le logiciel de base de données Oracle. Ne définissez pas cette variable lors de l'utilisation du client Oracle Instant. En effet, elle n'est pas nécessaire mais peut causer des problèmes lors de l'installation.

ORACLE_SID Le nom de la base de données sur la machine locale. Il n'est pas nécessaire de la définir lors de l'utilisation du client Oracle Instant, ou alors, passez la toujours comme paramètre de connexion à la fonction oci_connect().

LD_LIBRARY_PATH Définir cette variable (ou son équivalent sur la plateforme courante, comme LIBPATH, ou SHLIB_PATH) comme le chemin vers les bibliothèques Oracle, par exemple $ORACLE_HOME/lib ou /usr/lib/oracle/19/client/lib. Cette variable n'est pas nécessaire si les bibliothèques sont localisées par un mécanisme de recherche différent, comme avec ldconfig ou avec LD_PRELOAD au lieu de LD_LIBRARY_PATH.

NLS_LANG C'est la variable principale pour définir le jeu de caractères et les informations de globalisation utilisés par les bibliothèques Oracle.

ORA_SDTZ Définit le décalage horaire à utiliser par les sessions Oracle.

TNS_ADMIN Chemin vers le dossier contenant les fichiers de configuration Oracle Net Services (tnsnames.ora et sqlnet.ora). Inutile si la chaîne de connexion utilisée par la fonction oci_connect() est au format de connexion facile comme localhost/XE. Inutile également si les fichiers de configuration du réseau sont à des endroits par défaut comme /usr/lib/oracle/VERSION/client/lib/network/admin, $ORACLE_HOME/network/admin ou /etc.

Il existe d'autres variables d'environnement Oracle moins souvent utilisées, comme TWO_TASK, ORA_TZFILE, ainsi que les diverses variables de globalisation comme NLS* et ORA_NLS_*.

**Variables d'environnement Oracle communes**
Nom	But
ORACLE_HOME	Chemin vers le dossier contenant le logiciel de base de données Oracle. Ne définissez pas cette variable lors de l'utilisation du client Oracle Instant. En effet, elle n'est pas nécessaire mais peut causer des problèmes lors de l'installation.
ORACLE_SID	Le nom de la base de données sur la machine locale. Il n'est pas nécessaire de la définir lors de l'utilisation du client Oracle Instant, ou alors, passez la toujours comme paramètre de connexion à la fonction oci_connect().
LD_LIBRARY_PATH	Définir cette variable (ou son équivalent sur la plateforme courante, comme `LIBPATH`, ou `SHLIB_PATH`) comme le chemin vers les bibliothèques Oracle, par exemple `$ORACLE_HOME/lib` ou `/usr/lib/oracle/19/client/lib`. Cette variable n'est pas nécessaire si les bibliothèques sont localisées par un mécanisme de recherche différent, comme avec `ldconfig` ou avec `LD_PRELOAD` au lieu de `LD_LIBRARY_PATH`.
NLS_LANG	C'est la variable principale pour définir le jeu de caractères et les informations de globalisation utilisés par les bibliothèques Oracle.
ORA_SDTZ	Définit le décalage horaire à utiliser par les sessions Oracle.
TNS_ADMIN	Chemin vers le dossier contenant les fichiers de configuration Oracle Net Services (`tnsnames.ora` et `sqlnet.ora`). Inutile si la chaîne de connexion utilisée par la fonction oci_connect() est au format de connexion facile comme `localhost/XE`. Inutile également si les fichiers de configuration du réseau sont à des endroits par défaut comme `/usr/lib/oracle/VERSION/client/lib/network/admin`, `$ORACLE_HOME/network/admin` ou `/etc`.

En cas de problème

Le problème le plus courant lors de l'installation d'OCI8 est de ne pas avoir configuré correctement les variables d'environnement. C'est un problème typique lorsqu'on reçoit un message d'erreur lors de l'utilisation des fonctions oci_connect() ou oci_pconnect(). L'erreur peut être une erreur purement PHP comme Call to undefined function oci_connect(), une erreur Oracle comme ORA-12705 ou encore un arrêt brutal d'Apache. Vérifier le contenu des fichiers de log d'Apache lors de son démarrage et se reporter aux sections ci-dessus pour résoudre le problème.

Alors que les erreurs réseaux comme ORA-12154 ou ORA-12514 indiquent un problème quant au nommage du réseau ou un problème de configuration, bien souvent, la cause première est que l'environnement PHP n'est pas correctement défini et que les bibliothèques Oracle sont incapables de trouver le fichier de configuration tnsnames.ora.

Sous Windows, le fait d'avoir plusieurs versions d'Oracle sur la même machine peut facilement faire crasher l'installation tant que l'on ne s'est pas assuré que PHP n'utilise pas uniquement la bonne version d'Oracle.

Un utilitaire permettant d'examiner les bibliothèques recherchées et chargées peut aider quant à la résolution de ce genre de problème, tout particulièrement sous Windows.

Note: Si le serveur Web ne démarre pas ou échoue au démarrage

Vérifier qu'Apache est lié avec la bibliothèque pthread :
# ldd /www/apache/bin/httpd
  libpthread.so.0 => /lib/libpthread.so.0 (0x4001c000)
  libm.so.6 => /lib/libm.so.6 (0x4002f000)
  libcrypt.so.1 => /lib/libcrypt.so.1 (0x4004c000)
  libdl.so.2 => /lib/libdl.so.2 (0x4007a000)
  libc.so.6 => /lib/libc.so.6 (0x4007e000)
  /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
Si la bibliothèque libpthread n'est pas listée, réinstallez Apache :
# cd /usr/src/apache_1.3.xx
# make clean
# LIBS=-lpthread ./config.status
# make
# make install
À noter que sous des systèmes comme UnixWare, la bibliothèque s'appelle libthread au lieu de libpthread. PHP et Apache doivent être configurés avec EXTRA_LIBS=-lthread.