Introduction

Ces fonctions vous permettront d'accéder aux serveurs Oracle10, Oracle9, Ocracle 8 et Oracle7 en utilisant l'interface Oracle Call-Interface (OCI). Elle supporte le liage de variables PHP avec des marqueurs Oracle, a un support complet des LOB, FILE et ROWID, et vous permet d'utiliser des variables définies fournies par l'utilisateur.

Pré-requis

Vous avez besoin des bibliothèques Oracles pour utiliser cette extension. Les utilisateur Windows doivent les bibliothèques de version 10 ou supérieure pour se servir de la bibliothèque php_oci8.dll.

La meilleure façon d'installer tous les fichiers nécessaires est d'utiliser le client Oracle Instant, qui est disponible depuis : http://www.oracle.com/technology/tech/oci/instantclient/instantclient.html. Pour fonctionner avec OCI8, le module OCI8 "basic" du client Oracle Instant est suffisant. Le client Instant n'a pas besoin que les variables d'environnement ORACLE_SID ou ORACLE_HOME soient définies.Par contre, vous devez toujours définir les variables LD_LIBRARY_PATH et NLS_LANG.

Avant d'utiliser cette extension, assurez-vous que vous avez bien paramétré vos variables d'environnement Oracle, ainsi que votre démon utilisateur. Ces variables doivent être définies avant de démarrer votre serveur web. Les variables dont vous pouvez avoir besoin sont :

• ORACLE_HOME

• ORACLE_SID

• LD_PRELOAD

• LD_LIBRARY_PATH

• NLS_LANG

• ORA_NLS33

• NLS_LANG

Après avoir configuré ces variables pour votre utilisateur "serveur web", assurez-vous aussi d'ajouter cet utilisateur (nobody, www) au groupe Oracle.

Notez bien que sur certains systèmes comme UnixWare il faut utiliser libthread au lieu de libpthread. PHP et Apache doivent alors être configurés avec EXTRA_LIBS=-lthread.

Configuration à l'exécution

Le comportement de ces fonctions est affecté par la configuration dans le fichier php.ini.

Voici un éclaircissement sur l'utilisation des directives de configuration.

Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

Exemples

Exemple 3. Requête basique <?php $conn = oci_connect('hr', 'hr', 'orcl'); if (!$conn) {   $e = oci_error();   print htmlentities($e['message']);   exit; } $query = 'SELECT * FROM DEPARTMENTS'; $stid = oci_parse($conn, $query); if (!$stid) {   $e = oci_error($conn);   print htmlentities($e['message']);   exit; } $r = oci_execute($stid, OCI_DEFAULT); if (!$r) {   $e = oci_error($stid);   echo htmlentities($e['message']);   exit; } print '<table border="1">'; while ($row = oci_fetch_array($stid, OCI_RETURN_NULLS)) {   print '<tr>';    foreach ($row as $item) {      print '<td>'.($item?htmlentities($item):'&nbsp;').'</td>';    }    print '</tr>'; } print '</table>'; oci_close($conn); ?>

Exemple 4. Requête Insert avec des variables liées <?php // Avant d'exécuter, création de la table //   CREATE TABLE MYTABLE (mid NUMBER, myd VARCHAR2(20)); $conn = oci_connect('scott', 'tiger', 'orcl'); $query = 'INSERT INTO MYTABLE VALUES(:myid, :mydata)'; $stid = oci_parse($conn, $query); $id = 60; $data = 'Some data'; oci_bind_by_name($stid, ':myid', $id); oci_bind_by_name($stid, ':mydata', $data); $r = oci_execute($stid); if ($r) print "Une ligne a été insérée"; oci_close($conn); ?>

Exemple 5. Insertion de donnée dans une colonne CLOB <?php // Avant l'exécution, création de la table //     CREATE TABLE MYTABLE (mykey NUMBER, myclob CLOB); $conn = oci_connect('scott', 'tiger', 'orcl'); $mykey = 12343;  // clé arbitraire pour cet exemple; $sql = "INSERT INTO mytable (mykey, myclob) VALUES (:mykey, EMPTY_CLOB()) RETURNING myclob INTO :myclob"; $stid = oci_parse($conn, $sql); $clob = oci_new_descriptor($conn, OCI_D_LOB); oci_bind_by_name($stid, ":mykey", $mykey, 5); oci_bind_by_name($stid, ":myclob", $clob, -1, OCI_B_CLOB); oci_execute($stid, OCI_DEFAULT); $clob->save("A very long string"); oci_commit($conn); // Récupération des données CLOB $query = 'SELECT myclob FROM mytable WHERE mykey = :mykey'; $stid = oci_parse ($conn, $query); oci_bind_by_name($stid, ":mykey", $mykey, 5); oci_execute($stid, OCI_DEFAULT); print '<table border="1">'; while ($row = oci_fetch_array($stid, OCI_ASSOC)) {   $result = $row['MYCLOB']->load();   print '<tr><td>'.$result.'</td></tr>'; } print '</table>'; ?>

Vous pouvez facilement accéder aux procédures stockées, de la même façon que vous le feriez par ligne de commande :

Exemple 6. Utilisation de procédures stockées <?php // par webmaster@remoterealty.com $sth = oci_parse($dbh, "begin sp_newaddress( :address_id, '$firstname', '$lastname', '$company', '$address1', '$address2', '$city', '$state', '$postalcode', '$country', :error_code );end;" ); // Cela appelle la procédure stockée sp_newaddress, avec la variable :address_id // pour les entrées/sorties et :error_code comme variable de sortie. // Ensuite, vous faites les liaisons suivantes :    oci_bind_by_name($sth, ":address_id", $addr_id, 10);    oci_bind_by_name($sth, ":error_code", $errorcode, 10);    oci_execute($sth); ?>

Gestion de la connexion

L'extension oci8 fournit 3 fonctions différentes pour se connecter à Oracle. Il vous appartient d'utiliser la fonction la plus appropriée pour votre application ; les informations contenues dans cette section vont vous aider à faire le bon choix.

La connexion à un serveur Oracle est une opération résonnablement couteuse en terme de temps que cela prend. La fonction oci_pconnect() utilise un cache persistent de connexion qui peut être réutilisé à travers différents scripts. Cela signifie qu'une seule connexion sera utilisée par processus PHP (ou enfant Apache).

Si votre application se connecte à Oracle en utilisant un jeu différent de crédance pour chaque utilisateur web, le cache persistent utilisé par la fonction oci_pconnect() devient moins approprié car l'augmentation du nombre concurrent d'utilisateurs va affecté les performances de votre serveur Oracle, car il devra maintenir trop de connexions en cache. Si votre application est de ce type, il est recommandé d'optimiser votre application en utilisant les options de configuration oci8.max_persistent et oci8.persistent_timeout (elles vous donnent le contrôle sur la taille et la durée de vie du cache de connexions persistentes) ou utilisez oci_connect() à la place.

Les fonctions oci_connect() et oci_pconnect() employent un cache de connexion ; si vous faites des appels multiples à oci_connect(), en utilisant les mêmes paramètres dans un script donné, le second appel ainsi que les suivants retourneront le gestionnaire de connexion existant. Le cache utilisé par la fonction oci_connect() est nettoyé à la fin de l'exécution du script ou lorsque vous fermez explicitement le gestionnaire de connexion. oci_pconnect() a un comportement sensiblement identique, à la différence que le cache est maintenu séparemment et est conservé entre les requêtes.

Il est important de se souvenir de cette fonctionnalité de cache, car il donne l'apparence que les deux gestionnaires ne sont pas isolés transactionnellement (ils sont en faite le même gestionnaire de connexion, ils ne sont donc absolument pas isolés). Si votre connexion a besoin de deux connexions séparées, isolées transactionnellement, vous devez utiliser la fonction oci_new_connect().

oci_new_connect() crée toujours une nouvelle connexion au serveur Oracle, indépendamment de l'existante d'autres connexions. Les applications web à fort trafic doivent éviter d'utiliser oci_new_connect(), particulièrement dans les sections les plus chargées de l'application.

Types de données supportées par le driver