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 avoir Oracle version 8.1, et 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. 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.
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 :
Si la libpthread n'est pas listée, vous devez réinstaller Apache :
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
Nom | Par défaut | Modifiable | Changelog |
---|---|---|---|
oci8.privileged_connect | "0" | PHP_INI_SYSTEM | Devient disponible avec la version 1.1 du module oci8 |
oci8.max_persistent | "-1" | PHP_INI_SYSTEM | Devient disponible avec la version 1.1 du module oci8 |
oci8.persistent_timeout | "-1" | PHP_INI_SYSTEM | Devient disponible avec la version 1.1 du module oci8 |
oci8.ping_interval | "60" | PHP_INI_SYSTEM | Devient disponible avec la version 1.1 du module oci8 |
oci8.statement_cache_size | "20" | PHP_INI_SYSTEM | Devient disponible avec la version 1.1 du module oci8 |
oci8.default_prefetch | "10" | PHP_INI_SYSTEM | Devient disponible avec la version 1.1 du module oci8 |
oci8.old_oci_close_semantics | "0" | PHP_INI_SYSTEM | Devient disponible avec la version 1.1 du module oci8 |
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.
Mode d'exécution des commandes. La commande n'est pas validée automatiquement lorsqu'on utilise ce mode.
Mode d'exécution des commandes. Utilisez ce mode si vous ne souhaitez pas exécuter la commande, mais obtenir des descriptions.
Mode d'exécution des commandes. La commande est automatiquement validée après oci_execute().
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.
Utilisé avec la fonction oci_bind_by_name() pour relier des fichiers BFILE.
Utilisé avec la fonction oci_bind_by_name() pour relier des fichiers CFILE.
Utilisé avec oci_bind_by_name() pour relier des CLOB.
Utilisé avec oci_bind_by_name() pour relier des BLOB.
Utilisé avec oci_bind_by_name() pour relier des ROWID.
Utilisé avec oci_bind_by_name() pour relier des curseurs, précédemment alloués avec oci_new_descriptor().
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.
Identique à OCI_B_BFILE.
Identique à OCI_B_CFILEE.
Identique à OCI_B_CLOB.
Identique à OCI_B_BLOB.
Identique à OCI_B_ROWID.
Identique à OCI_B_NTY.
Mode par défaut de oci_fetch_all().
Mode alternatif pour oci_fetch_all().
Utilisé avec oci_fetch_all() et oci_fetch_array() pour lire un tableau associatif.
Utilisé avec oci_fetch_all() et oci_fetch_array() pour lire un tableau énuméré.
Utilisé avec oci_fetch_all() et oci_fetch_array() pour lire un tableau associatif et énuméré.
Utilisé avec oci_fetch_array() pour obtenir des éléments vides, si la valeur du champ est NULL.
Utilisé avec oci_fetch_array() pour obtenir la valeur du LOB au lieu du pointeur.
Cette option indique à oci_new_descriptor() d'initialiser un nouveau pointeur FILE.
Cette option indique à oci_new_descriptor() d'initialiser un nouveau pointeur LOB.
Cette option indique à oci_new_descriptor() d'initialiser un nouveau pointeur ROWID.
Identique à OCI_DTYPE_FILE.
Identique à OCI_DTYPE_LOB.
Identique à OCI_DTYPE_ROWID.
Utilisé avec oci_connect() pour se connecter comme SYSOPER utilisant des créances externes (oci8.privileged_connect doit être activé pour utiliser cette constante).
Utilisé avec oci_connect() pour se connecter comme SYSDBA utilisant des créances externes (oci8.privileged_connect doit être activé pour utiliser cette constante).
Utilisé avec OCI-Lob->flush pour libérer les buffers utilisés.
Utilisé avec OCI-Lob->writeTemporary pour indiquer explicitement que un CLOB temporaire doit être créé.
Utilisé avec OCI-Lob->writeTemporary pour indiquer explicitement que un BLOB temporaire doit être créé.
Exemple 3. Requête basique
|
Exemple 4. Requête Insert avec des variables liées
|
Exemple 5. Insertion de donnée dans une colonne CLOB
|
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
|
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 2. 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 3. 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 |
Précédent | Sommaire | Suivant |
overload | Niveau supérieur | OCI-Collection->append |