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 :
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 1790. 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 :
Exemple 1791. 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 224. Options de configuration
| Nom | Par défaut | Modifiable | Historique |
|---|---|---|---|
| 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.
Cette option active les connexions privilégiées en utilisant les crédances externes (OCI_SYSOPER , OCI_SYSDBA ).
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.
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.
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.
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.
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.
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.
Exemple 1792. 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
):
' '
).
'</td>'
;
}
print
'</tr>'
;
}
print
'</table>'
;
oci_close
(
$conn
);
?>
Exemple 1793. 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 1794. 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 1795. 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
);
?>
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.
Tableau 225. 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. |
Tableau 226. 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 |