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.

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

Pour les variables d’environnement Oracle moins fréquemment utilisées comme TNS_ADMIN, TWO_TASK, ORA_TZFILE ainsi que les diverses configurations globales Oracle comme les variables ORA_NLS33, ORA_NLS10 et NLS_*, référez-vous à la documentation Oracle.

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

Si votre serveur web ne démarre pas ou plante au démarrage avec Oracle : Vérifiez que Apache a bien été compilé avec la bibliothèque pthread :
| Exemple 1. Configuration Apache avec 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 (0×40000000) | |
Si la libpthread n’est pas listée, vous devez réinstaller Apache :
| Exemple 2. Reinstaller Apache avec pthread | # cd /usr/src/apache_1.3.xx # make clean # LIBS=-lpthread ./config.status # make # make install | |

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.

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

Tableau 1. Options de configuration

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

“oci8.privileged_connect” boolean

Cette option active les connexions privilégiées en utilisant les crédances externes (”OCI_SYSOPER”, “OCI_SYSDBA”).

“oci8.max_persistent” int

Le nombre maximal de connexions persistantes OCI8 par processus. Le fait de définir cette option à -1 signifie qu’il n’y a aucune limite.

“oci8.persistent_timeout” int

Le délai maximal (en secondes) q’un processs donné est autorisé à maintenir une connexion persistante. Le fait de définir cette option à -1 signifie que les connexions persistantes seront toujours maintenues.

“oci8.ping_interval” int

Le délai maximal (en secondes) à attendre avant d’envoyer un ping durant oci_pconnect(). Lorsque définie à 0, les connexions persistantes seront pingugées à chaque réutilisation. Pour désactiver complètement les pings, déifnissez cette option à -1.

Note : Le fait de désactiver les pings rende les appels à oci_pconnect() hautement rentables, mais cela empèche PHP de détecter les problèmes de connexion, comme les problèmes de réseau, ou si le serveur Oracle a été éteint depuis la connexion de PHP. Consultez la documentation de la fonction oci_pconnect() pour plus d’informations.

“oci8.statement_cache_size” int

Cette option active la mise en cache des requêtes, et spécifie le nombre de requêtes à mettre en cache. Pour désactiver la mise en cache des requêtes, définissez cette option à 0.

Note : Un énorme cache peut accroître les performances, mais causera un accroissement de la mémoire.

“oci8.default_prefetch” int

Cette option active la prérécupération des requêtes et définie le nombre de lignes par défaut à récupérer automatiquement après l’exécution de la requête.

Note : Une large prérécupération peut accroître les performances, mais causera un accroissement de la mémoire.

“oci8.old_oci_close_semantics” boolean

Cette option contrôle le comportement de la fonction oci_close(). Activer cette option signifie que oci_close() ne fera rien du tout ; la connexion ne sera pas fermée tant que la fin du script ne sera pas atteinte. Ceci est uniquement pour assurer une compatibilité ascendante. Si vous pensez que vous devez activer cette option, vous êtes vivement encouragé à effacer les appels à la fonction oci_close() de votre application au lieu d’activer cette option.

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.

“OCI_DEFAULT” (entier)

Mode d’exécution des commandes. La commande n’est pas validée automatiquement lorsqu’on utilise ce mode.

“OCI_DESCRIBE_ONLY” (entier)

Mode d’exécution des commandes. Utilisez ce mode si vous ne souhaitez pas exécuter la commande, mais obtenir des descriptions.

“OCI_COMMIT_ON_SUCCESS” (entier)

Mode d’exécution des commandes. La commande est automatiquement validée après oci_execute().

“OCI_EXACT_FETCH” (entier)

Mode de lecture de résultats. Utilisé lorsque les applications savent à l’avance le nombre de ligne qu’il faudra lire. Ce mode désactive la lecture anticipée d’Oracle version 8 et plus récente. Le curseur est annulé une fois que le nombre de lignes à lire a été atteint, et cela réduit les ressources consommées côté serveur.

“OCI_SYSDATE” (entier)

“SQLT_BFILEE” (entier)

Utilisé avec la fonction oci_bind_by_name() pour relier des fichiers BFILE.

“SQLT_CFILEE” (entier)

Utilisé avec la fonction oci_bind_by_name() pour relier des fichiers CFILE.

“OCI_B_CLOB” (entier)

Utilisé avec oci_bind_by_name() pour relier des CLOB.

“OCI_B_BLOB” (entier)

Utilisé avec oci_bind_by_name() pour relier des BLOB.

“OCI_B_ROWID” (entier)

Utilisé avec oci_bind_by_name() pour relier des ROWID.

“OCI_B_CURSOR” (entier)

Utilisé avec oci_bind_by_name() pour relier des curseurs, précédemment alloués avec oci_new_descriptor().

“OCI_B_NTY” (entier)

Utilisé avec oci_bind_by_name() pour relier des noms de types de données. Note : En PHP < 5.0, il était nommé “OCI_B_SQLT_NTY”.

“OCI_B_BIN” (entier)

“SQLT_BFILEE” (entier)

Identique à “OCI_B_BFILE”.

“SQLT_CFILEE” (entier)

Identique à “OCI_B_CFILEE”.

“SQLT_CLOB” (entier)

Identique à “OCI_B_CLOB”.

“SQLT_BLOB” (entier)

Identique à “OCI_B_BLOB”.

“SQLT_RDD” (entier)

Identique à “OCI_B_ROWID”

“SQLT_NTY” (entier)

Identique à “OCI_B_NTY”

“SQLT_LNG” (entier)

Utilisé avec oci_bind_by_name() pour lier les valeurs LONG.

“SQLT_LBI” (entier)

Utilisé avec oci_bind_by_name() pour lier les valeurs LONG RAW.

“SQLT_BIN” (entier)

Utilisé avec oci_bind_by_name() pour lier les valeurs RAW.

“SQLT_NUM” (entier)

Utilisé avec oci_bind_array_by_name() pour lier les tableaux de NUMBER

“SQLT_INT” (entier)

Utilisé avec oci_bind_array_by_name() pour lier les tableaux de INTEGER

“SQLT_AFC” (entier)

Utilisé avec oci_bind_array_by_name() pour lier les tableaux de CHAR

“SQLT_CHR” (entier)

Utilisé avec oci_bind_array_by_name() pour lier les tableaux de VARCHAR2. Utilisé également avec oci_bind_by_name().

“SQLT_VCS” (entier)

Utilisé avec oci_bind_array_by_name() pour lier les tableaux de VARCHAR

“SQLT_AVC” (entier)

Utilisé avec oci_bind_array_by_name() pour lier les tableaux de CHARZ

“SQLT_STR” (entier)

Utilisé avec oci_bind_array_by_name() pour lier les tableaux de STRING

“SQLT_LVC” (entier)

Utilisé avec oci_bind_array_by_name() pour lier les tableaux de LONG VARCHAR

“SQLT_FLT” (entier)

Utilisé avec oci_bind_array_by_name() pour lier les tableaux de FLOAT

“SQLT_ODT” (entier)

Utilisé avec oci_bind_array_by_name() pour lier les tableaux de LONG

“SQLT_BDOUBLE” (entier)

“SQLT_BFLOAT” (entier)

“OCI_FETCHSTATEMENT_BY_COLUMN” (entier)

Mode par défaut de oci_fetch_all().

“OCI_FETCHSTATEMENT_BY_ROW” (entier)

Mode alternatif pour oci_fetch_all().

“OCI_ASSOC” (entier)

Utilisé avec oci_fetch_all() et oci_fetch_array() pour lire un tableau associatif.

“OCI_NUM” (entier)

Utilisé avec oci_fetch_all() et oci_fetch_array() pour lire un tableau énuméré.

“OCI_BOTH” (entier)

Utilisé avec oci_fetch_all() et oci_fetch_array() pour lire un tableau associatif et énuméré.

“OCI_RETURN_NULLS” (entier)

Utilisé avec oci_fetch_array() pour obtenir des éléments vides, si la valeur du champ est “NULL”.

“OCI_RETURN_LOBS” (entier)

Utilisé avec oci_fetch_array() pour obtenir la valeur du LOB au lieu du pointeur.

“OCI_DTYPE_FILE” (entier)

Cette option indique à oci_new_descriptor() d’initialiser un nouveau pointeur FILE.

“OCI_DTYPE_LOB” (entier)

Cette option indique à oci_new_descriptor() d’initialiser un nouveau pointeur LOB.

“OCI_DTYPE_ROWID” (entier)

Cette option indique à oci_new_descriptor() d’initialiser un nouveau pointeur ROWID.

“OCI_D_FILE” (entier)

Identique à “OCI_DTYPE_FILE”.

“OCI_D_LOB” (entier)

Identique à “OCI_DTYPE_LOB”.

“OCI_D_ROWID” (entier)

Identique à “OCI_DTYPE_ROWID”.

“OCI_SYSOPER” (entier)

“OCI_SYSDBA” (entier)

“OCI_LOB_BUFFER_FREE” (entier)

Utilisé avec OCI-Lob->flush pour libérer les buffers utilisés.

“OCI_TEMP_CLOB” (entier)

Utilisé avec OCI-Lob->writeTemporary pour indiquer explicitement que un CLOB temporaire doit être créé.

“OCI_TEMP_BLOB” (entier)

Utilisé avec OCI-Lob->writeTemporary pour indiquer explicitement que un BLOB temporaire doit être créé.

<?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);
?>

<?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);
 
?>

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

<?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);
 
?>

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

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.

Tableau 2. Le driver supporte les types suivants lors du liage de paramètres en utilisant la fonction oci_bind_by_name() :

Tableau 3. Les types suivants sont supportés lors de la récupération de colonnes depuis un jeu de résultats :

Table des matières

OCI-Collection->append – Ajoute un élément à une collection OracleOCI-Collection->assign – Assigne une valeur à une collection depuis une autre collection OracleOCI-Collection->assignElem – Assigne une valeur à un élément d’une collection OracleOCI-Collection->free – Libère les ressources associées avec un objet de collectionOCI-Collection->getElem – Retourne la valeur d’un élément d’une collection OracleOCI-Collection->max – Retourne le nombre maximal de valeurs d’une collection OracleOCI-Collection->size – Retourne la taille d’une collection OracleOCI-Collection->trim – Supprime les derniers éléments d’une collection OracleOCI-Lob->append – Ajoute des données à un LOB OracleOCI-Lob->close – Ferme un LOB OracleOCI-Lob->eof – Teste la fin du LOB OracleOCI-Lob->erase – Ecrase une partie d’un LOB OracleOCI-Lob->export – Exporte un LOB Oracle dans un fichierOCI-Lob->flush – Ecrit les LOB Oracle sur le disqueOCI-Lob->free – Détruit un pointeur de LOB OracleOCI-Lob->getBuffering – Retourne l’état de bufferisation LOB d’OracleOCI-Lob->import – Importe un fichier dans LOB OracleOCI-Lob->load – Returns large object’s contentsOCI-Lob->read – Lit une partie d’un LOB OracleOCI-Lob->rewind – Ramène le pointeur interne d’un LOB Oracle au débutOCI-Lob->save – Sauve des données dans un LOB OracleOCI-Lob->saveFile – Alias de oci_lob_import()
OCI-Lob->seek – Déplace le pointeur interne d’un LOB OracleOCI-Lob->setBuffering – Active/désactive la bufferisation des LOB OracleOCI-Lob->size – Retourne la taille d’un LOB OracleOCI-Lob->tell – Retourne la position courante du pointeur de LOBOCI-Lob->truncate – Tronque un LOB OracleOCI-Lob->write – Ecrit des données dans un LOB OracleOCI-Lob->writeTemporary – Ecrit un LOB Oracle temporaireOCI-Lob->writeToFile – Alias de oci_lob_export()
oci_bind_array_by_name –  Lie un tableau PHP à un tableau Oracle PL/SQL par son nom oci_bind_by_name –  Associe une variable PHP à une variable SQL Oracle oci_cancel – Termine la lecture de ressources Oracleoci_close – Ferme une connexion Oracleoci_commit – Valide les transactions Oracle en coursoci_connect – Etablit une connexion avec un serveur Oracleoci_define_by_name –  Utilise une variable PHP pour la phase de définition, dans une commande SELECT Oracle oci_error – Retourne la dernière erreur Oracleoci_execute – Exécute une commande SQL Oracleoci_fetch_all – Lit toutes les lignes d’un résultat Oracleoci_fetch_array – Lit une ligne d’un résultat Oracle sous forme de tableau oci_fetch_assoc – Lit une ligne d’un résultat Oracle sous forme de tableau associatifoci_fetch_object – Lit une ligne d’un résultat Oracle sous forme d’objetoci_fetch_row – Lit une ligne d’un résultat Oracle sous forme de tableauoci_fetch –  Lit la prochaine ligne dans le résultat Oracle oci_field_is_null – Teste si la valeur d’une colonne Oracle est “NULL”oci_field_name – Retourne le nom d’une colonne Oracleoci_field_precision – Lit la précision d’une colonne Oracleoci_field_scale – Lit l’échelle d’une colonne Oracleoci_field_size – Retourne la taille d’un champ Oracleoci_field_type_raw – Lit directement le type de colonne Oracleoci_field_type – Retourne le type de données d’un champ Oracleoci_free_statement –  Libère toutes les ressources réservées par un résultat Oracle oci_internal_debug –  Active ou désactive l’affichage des données de débogage Oracle oci_lob_copy – Copie un LOB Oracleoci_lob_is_equal – Compare deux LOB/FILE Oracleoci_new_collection – Initialise une nouvelle collection Oracleoci_new_connect – Etablit une nouvelle connexion à Oracleoci_new_cursor – Alloue un nouveau curseur Oracleoci_new_descriptor – Initialise un nouveau pointeur vide de LOB/FILE Oracleoci_num_fields –  Retourne le nombre de colonnes dans un résultat Oracle oci_num_rows –  Retourne le nombre de lignes affectées durant la dernière commande Oracle oci_parse – Prépare une requête SQL avec Oracleoci_password_change – Modifie le mot de passe d’un utilisateur Oracleoci_pconnect – Ouvre une connexion persistante à un serveur Oracleoci_result – Retourne la valeur d’une colonne dans un résultat Oracleoci_rollback – Annule les transactions Oracle en coursoci_server_version –  Retourne une chaîne contenant les informations de version du serveur Oracle oci_set_prefetch –  Indique le nombre de lignes qui doivent être lues à l’avance par Oracle oci_statement_type – Retourne le type de commande Oracleocibindbyname – Alias de oci_bind_by_name()
ocicancel – Alias de oci_cancel()
ocicloselob – Alias de OCI-Lob->close
ocicollappend – Alias de OCI-Collection->append
ocicollassign – Alias de OCI-Collection->assign
ocicollassignelem – Alias de OCI-Collection->assignElem
ocicollgetelem – Alias de OCI-Collection->getElem
ocicollmax – Alias de OCI-Collection->max
ocicollsize – Alias de OCI-Collection->size
ocicolltrim – Alias de OCI-Collection->trim
ocicolumnisnull – Alias de oci_field_is_null()
ocicolumnname – Alias de oci_field_name()
ocicolumnprecision – Alias de oci_field_precision()
ocicolumnscale – Alias de oci_field_scale()
ocicolumnsize – Alias de oci_field_size()
ocicolumntype – Alias de oci_field_type()
ocicolumntyperaw – Alias de oci_field_type_raw()
ocicommit – Alias de oci_commit()
ocidefinebyname – Alias de oci_define_by_name()
ocierror – Alias de oci_error()
ociexecute – Alias de oci_execute()
ocifetch – Alias de oci_fetch()
ocifetchinto –  Retourne la ligne suivante d’un résultat Oracle dans un tableau ocifetchstatement – Alias de oci_fetch_all()
ocifreecollection – Alias de OCI-Collection->free
ocifreecursor – Alias de oci_free_statement()
ocifreedesc – Alias de OCI-Lob->free
ocifreestatement – Alias de oci_free_statement()
ociinternaldebug – Alias de oci_internal_debug()
ociloadlob – Alias de OCI-Lob->load
ocilogoff – Alias de oci_close()
ocilogon – Alias de oci_connect()
ocinewcollection – Alias de oci_new_collection()
ocinewcursor – Alias de oci_new_cursor()
ocinewdescriptor – Alias de oci_new_descriptor()
ocinlogon – Alias de oci_new_connect()
ocinumcols – Alias de oci_num_fields()
ociparse – Alias de oci_parse()
ociplogon – Alias de oci_pconnect()
ociresult – Alias de oci_result()
ocirollback – Alias de oci_rollback()
ocirowcount – Alias de oci_num_rows()
ocisavelob – Alias de OCI-Lob->save
ocisavelobfile – Alias de OCI-Lob->import
ociserverversion – Alias de oci_server_version()
ocisetprefetch – Alias de oci_set_prefetch()
ocistatementtype – Alias de oci_statement_type()
ociwritelobtofile – Alias de OCI-Lob->export
ociwritetemporarylob – Alias de OCI-Lob->writeTemporary