Forum und email
Référence des fonctions
PHP Manual

Fonctions Oracle

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 : » https://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.

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

Example#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 (0x40000000)

Si la libpthread n'est pas listée, vous devez réinstaller Apache :

Example#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.

Configuration à l'exécution

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

Options de configuration
NomPar défaut ModifiableHistorique
oci8.privileged_connect "0" PHP_INI_SYSTEM Disponible depuis PHP 5.1.2.
oci8.max_persistent "-1" PHP_INI_SYSTEM Disponible depuis PHP 5.1.2.
oci8.persistent_timeout "-1" PHP_INI_SYSTEM Disponible depuis PHP 5.1.2.
oci8.ping_interval "60" PHP_INI_SYSTEM Disponible depuis PHP 5.1.2.
oci8.statement_cache_size "20" PHP_INI_SYSTEM Disponible depuis PHP 5.1.2.
oci8.default_prefetch "10" PHP_INI_SYSTEM Disponible depuis PHP 5.1.2.
oci8.old_oci_close_semantics "0" PHP_INI_SYSTEM Disponible depuis PHP 5.1.2.

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.

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.

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)
Utilisé avec oci_connect() pour se connecter comme SYSOPER utilisant des créances externes (oci8.privileged_connect doit être activé pour utiliser cette constante).
OCI_SYSDBA (entier)
Utilisé avec oci_connect() pour se connecter comme SYSDBA utilisant des créances externes (oci8.privileged_connect doit être activé pour utiliser cette constante).
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éé.

Exemples

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

Example#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);

?>

Example#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 :

Example#6 Utilisation de procédures stockées

<?php
// par [email protected]
$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

Le driver supporte les types suivants lors du liage de paramètres en utilisant la fonction oci_bind_by_name() :
Type Liage
SQLT_NTY Lie une collection de types natifs depuis un objet de collection PHP comme ceux créés par oci_new_collection().
SQLT_BFILEE Lie un descripteur natif, comme ceux créés par la fonction oci_new_descriptor().
SQLT_CFILEE Lie un descripteur natif, comme ceux créés par la fonction oci_new_descriptor().
SQLT_CLOB Lie un descripteut natif, comme ceux créés par la fonction oci_new_descriptor().
SQLT_BLOB Lie un descripteur natif, comme ceux créés par la fonction oci_new_descriptor().
SQLT_RDD Lie un descripteur natif, comme ceux créés par la fonction oci_new_descriptor().
SQLT_NUM Convertie un paramètre PHP en un type long 'C', et le lie à cette valeur.
SQLT_RSET Lie un gestionnaire de requête natif, comme ceux créés par la fonction oci_parse() ou ceux récupérés depuis d'autres requêtes OCI.
SQLT_CHR and any other type Convertie le paramètre PHP en un type chaîne de caractères et le lie en tant que chaîne de caractères.
Les types suivants sont supportés lors de la récupération de colonnes depuis un jeu de résultats :
Type Liage
SQLT_RSET Crée une ressource de requêtes oci pour représenter le curseur.
SQLT_RDD Crée un objet ROWID.
SQLT_BLOB Crée un objet LOB.
SQLT_CLOB Crée un objet LOB.
SQLT_BFILE Crée un objet LOB.
SQLT_LNG Limite à SQLT_CHR, retourné sous la forme d'une chaîne de caractères
SQLT_LBI Limite à SQLT_BIN, retourné sous la forme d'une chaîne de caractères
Any other type Limite à SQLT_CHR, retourné sous la forme d'une chaîne de caractères

Table of Contents

Référence des fonctions
PHP Manual