Configuration de PHP avec OCI8

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

Pour activer l'extension OCI8, configurez PHP avec l'option --with-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 vous compilez OCI8 avec les bibliothèques Oracle 11.2, alors PHP doit aussi être déployé et exécuté avec les bibliothèques Oracle 11.2. 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 OCI8 comme extension partagée

L'option de configuration shared permet de construire OCI8 comme bibliothèque partagée qui pourra être chargée dynamiquement dans PHP. Le fait de construire une extension partagée permet à OCI8 d'être mis à jour plus facilement sans pour autant impacter le reste de PHP.

Configure OCI8 en utilisant une des options de configuration suivantes :

• Si vous utilisez les bibliothèques gratuites » Oracle Instant Client, alors vous pouvez faire :

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

  Si le client Oracle Instant est installé depuis des fichiers compressées, assurez-vous de créer d'abord le lien symbolique vers la bibliothèque, par exemple, ln -s libclntsh.so.12.1 libclntsh.so.

  Si vous utilisez une installation du client Oracle Instant à base de paquets RPM, 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/12.1/client/lib.

  Notez que le support du client Oracle Instant est apparu pour la première fois en PHP 4.3.11 et 5.0.4, et utilisait à l'époque l'option de configuration PHP --with-oci8-instant-client.

• Si vous utilisez une base de données oracle ou une installation Oracle client complète, alors faîtes :

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

  Assurez-vous 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é) dans le dossier $ORACLE_HOME. Avec Oracle 10gR2, vous devez avoir besoin d'exécuter l'utilitaire $ORACLE_HOME/install/changePerm.sh pour donner accès à ce dossier.

Après la configuration, suivez la procédure de compilation habituelle pour PHP, i.e. make install. L'extension partagée OCI8 oci8.sosera ainsi créée. Il se peut que vous ayez besoin de la déplacer manuellement dans le dossier d'extensions PHP, spécifié par l'option extension_dir de votre fichier php.ini.

Pour compléter l'installation d'OCI8, éditez votre fichier php.ini et ajoutez-y cette ligne :

extension=oci8.so

Installation d'OCI8 comme extension compilée statiquement

Configurez PHP pour inclure OCI8 en utilisant une des options de configuration suivante :

• Si vous utilisez le client Oracle Instant, faîtes ceci :

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

• Si vous utilisez une base de données Oracle ou une installation client complète d'Oracle, alors faîtes ceci :

  ./configure --with-oci8=$ORACLE_HOME
  

Après configuration, suivez la procédure de compilation habituelle de PHP, i.e. make install. Après une compilation réussie, vous n'avez pas besoin d'ajouter le fichier oci8.so à votre fichier php.ini. Aucune autre étape de compilation n'est nécessaire.

Installation d'OCI8 depuis PECL

L'extension OCI8 peut être ajoutée à une installation PHP existante soit automatiquement, soit manuellement depuis » PECL.

Pour une installation automatique, suivez les étapes suivantes :

• Si vous être derrière un part-feu, définissez le proxy PEAR, par exemple :

  pear config-set http_proxy http://my-proxy.example.com:80/
  

• Exécutez :

  pecl install oci8
  

  Lorsque vous avez de nouveau la main, entrez soit la valeur de la variable $ORACLE_HOME, soit instantclient,/path/to/instant/client/lib.

  Note : N'entrez pas la variable $ORACLE_HOME car elle ne sera pas analysée. A la place, entrez le chemin actuel du dossier principal d'Oracle.

Pour une installation manuelle (lorsque la commande pecl n'est pas disponible), téléchargez le paquet PECL OCI8, i.e. oci8-1.4.10.tgz.

• Extraire le paquet :

  tar -zxf oci8-1.4.10.tgz
  cd oci8-1.4.10
  

• Préparez le paquet :

  phpize
  

• Configurez le paquet, soit en utilisant $ORACLE_HOME, soit en utilisant le client Oracle Instant

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

  or

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

• Installez le paquet :

  make install
  

Après une installation automatique ou manuelle, éditez votre fichier php.ini et ajoutez la ligne :

extension=oci8.so

Assurez-vous que la directive extension_dir de votre php.ini est définie au dossier dans lequel oci8.so a été installé.

Installation d'OCI8 sous Windows

Lors de l'utilisation des bibliothèques clientes Oracle Oracle 10gR2 sous Windows, dé-commentez la ligne extension=php_oci8.dll de votre fichier php.ini. Lors de l'utilisation des bibliothèques clientes Oracle 11gR2 ou supérieurs, dé-commentez la ligne extension=php_oci8_11g.dll ou la ligne extension=php_oci8.dll. Avec les bibliothèques clientes Oracle 12c, utilisez extension=php_oci8_12c.dll ou extension=php_oci8_11g.dll, ou bien extension=php_oci8.dll. Seule une de ces DLLs doivt ê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. Assurez-vous que l'option extension_dir est définie sur le dossier contenant les extensions DLLs de PHP.

Si vous utilisez le 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, assurez-vous que les variables d'environnement Oracle sont correctement définies pour l'utilisateur exécutant le serveur Web. Si votre serveur Web est automatiquement démarré au démarrage de votre serveur, alors assurez-vous également de la bonne configuration de la variable d'environnement utilisé à ce moment ci.

Note:

Ne définissez pas les variables d'environnement Oracle en utilisant la fonction putenv() dans vos scripts PHP, car les bibliothèques Oracle sont chargées et initialisées avant l'exécution de votre script. Les variables définies avec putenv() pourraient ainsi entrer en conflit et provoquer aussi bien des crashs que des comportements totalement inattendu. 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, vous devez exporter les variables à la fin du fichier /etc/sysconfig/httpd. Sous les autres systèmes utilisant Apache 2, vous devez utiliser le script envvars que vous trouverez 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, utilisez la fonction phpinfo() et attardez-vous sur la section Environment (et non la section Apache Environment) ; elle doit contenir toutes les variables définies.

Les variables qui doivent vous êtes nécessaires sont inclues dans la table suivante. Reportez-vous à la documentation Oracle pour plus d'informations sur toutes les variables.

En cas de problème

Le problème le plus courant lors de l'installation d'OCI8 est d'avoir mal configuré le jeu de variables d'environnement correctement. C'est un problème typique lorsque vous recevez 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érifiez le contenu des fichiers de log d'Apache lors de son démarrage et reportez-vous 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 vous ne vous êtes pas assuré que PHP n'utilise pas uniquement la bonne version d'Oracle.

Un utilitaire permettent d'examiner les bibliothèques recherchées et chargées peut vous 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érifiez 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é, réinstallez Apache :

# cd /usr/src/apache_1.3.xx
# make clean
# LIBS=-lpthread ./config.status
# make
# make install

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