Manuel PHP
Précédent |  | Suivant

# CXIII. Fonctions PDO

# Introduction

L'extension PHP Data Objects (PDO) définit une excellente interface pour accéder à une base de données depuis PHP. Chaque pilote de base de données implémenté dans l'interface PDO peut utiliser des fonctionnalités spécifiques de chacune des bases de données en utilisant des extensions de fonctions. Notez que vous ne pouvez exécuter aucune fonction de base de données en utilisant l'extension PDO par elle-même ; vous devez utiliser un driver PDO spécifique à la base de données pour accéder au serveur de base de données.

PDO fournit une interface d'abstraction à l'accès de données, ce qui signifie que vous utilisez les mêmes fonctions pour exécuter des requêtes ou récupérer les données quelque soit la base de données utilisée. PDO ne fournit pas une abstraction de base de données : il ne réécrit pas le SQL, n'émule pas des fonctionnalités manquantes. Vous devriez utiliser une interface d'abstraction complète si vous avez besoin de cela.

PDO est fournit avec PHP 5.1 et est disponible en tant qu'extension PECL pour PHP 5.0 ; PDO requiert les nouvelles fonctionnalités OO fournies par PHP 5 et donc, ne fonctionne pas avec les versions antérieures de PHP.

# Installation

PHP 5.1 et supérieur sur les systèmes Unix

1. Si vous exécutez une version 5.1 de PHP, PDO est inclut dans cette distribution ; il devrait être automatiquement activé lorsque vous lancerez le script de configuration de PHP. Il est recommandé de compiler PDO en tant qu'extension partagée, ce qui vous permettra de mettre à jour PDO via PECL. Il est également recommandé d'activer le support zlib (pour l'installeur PEAR) lors de la compilation de PHP. Vous devriez également avoir besoin d'activer le driver PDO correspondant à la base de données de votre choix ; consultez la documentation pour les drivers PDO spécifiques à une base de données pour plus d'informations.

       ./configure --with-zlib --enable-pdo=shared

2. Après avoir installé PDO en tant que module partagé, vous devez éditer votre fichier `php.ini` afin que l'extension PDO soit chargée automatiquement lorsque PHP est lancé. Vous devez y activer également le driver spécifique à votre base de données ; assurez-vous qu'ils sont listés après la ligne pdo.so, car PDO doit être initialisé avant le chargement des extensions spécifiques à la base de données. Si vous avez compilé les extensions statiquement, vous pouvez sauter cette étape.

       extension=pdo.so

3. Le fait d'avoir PDO en tant que module partagé vous permet d'exécuter la commande pear upgrade pdo pour mettre à jour votre version de PDO sans pour autant avoir besoin de recompiler complètement PHP. Notez que si vous faites cela, vous devez également mettre à jour votre driver PDO spécifique à votre base de données en même temps.

PHP 5.0 et supérieur sur les systèmes Unix

1. PDO est disponible en tant qu'extension PECL depuis http://pecl.php.net/package/pdo. L'installation peut être faite via la commande pear ; ceci est activé par défaut lorsque vous configurez PHP. Vous devriez vous assurer que PHP a été configuré avec --with-zlib pour pouvoir utiliser la commande pear afin de gérer les paquets compressés.

2. Exécutez la commande suivante pour télécharger, compiler et installer la dernière version stable de PDO :

       pear install pdo

3. Si PDO est toujours en version BETA (et au moment de l'écriture de ces lignes, il l'est), vous devez demander à l'utilitaire PEAR de récupérer le paquet BETA. Au lieu d'exécuter la commande ci-dessus, lancez la commande suivante :

       pear install pdo-beta

4. La commande pear installe automatiquement le module PDO dans votre dossier d'extensions PHP. Pour activer l'extension PDO sous les systèmes Linux ou Unix, vous devez ajouter la ligne suivante dans votre fichier `php.ini` :

       extension=pdo.so

   Pour plus d'informations sur la compilation de paquets PECL, consultez la section sur l'installation de PECL du manuel.

Utilisateurs de Windows avec PHP 5.1 et supérieur

1. PDO ainsi que tous les drivers principaux interagissent avec PHP en tant qu'extensions partagées, et ont tout simplement besoin d'être activés en éditant le fichier `php.ini` :

       extension=php_pdo.dll

2. Ensuite, choisissez les autres fichiers DLL spécifiques à votre base de données et utilisez soit la fonction dl() pour les charger au moment de l'exécution ou activer-les dans le fichier `php.ini` en dessous de la ligne `php_pdo.dll`. Par exemple :

       extension=php_pdo.dll
       extension=php_pdo_firebird.dll
       extension=php_pdo_informix.dll
       extension=php_pdo_mssql.dll
       extension=php_pdo_mysql.dll
       extension=php_pdo_oci.dll
       extension=php_pdo_oci8.dll
       extension=php_pdo_odbc.dll
       extension=php_pdo_pgsql.dll
       extension=php_pdo_sqlite.dll

   Ces bibliothèques DDLs doivent exister dans le dossier système extension_dir. Notez que PDO_INFORMIX est seulement disponible en tant qu'extension PECL.

# Configuration à l'exécution

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

Tableau 1. Options de Configuration PDO

Nom | Par défaut | Modifiable | Historique
--- | --- | --- | ---
pdo.dsn.* |  | `php.ini` seulement |

Pour plus de détails sur les constantes PHP_INI_*, reportez-vous à Annexe G.

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

pdo.dsn.* string

  Définit un alias DSN. Voyez PDO::__construct pour une explication complète.

# Drivers PDO

Les drivers suivants sont actuellement implémentés dans l'interface PDO :

Nom du driver | Bases de données supportées
--- | ---
PDO_DBLIB | FreeTDS / Microsoft SQL Server / Sybase
PDO_FIREBIRD | Firebird/Interbase 6
PDO_INFORMIX | IBM Informix Dynamic Server
PDO_MYSQL | MySQL 3.x/4.0
PDO_OCI | Oracle Call Interface
PDO_ODBC | ODBC v3 (IBM DB2 unixODBC et win32 ODBC)
PDO_PGSQL | PostgreSQL
PDO_SQLITE | SQLite 3 et SQLite 2

# Connexions et gestionnaire de connexion

Les connexions sont établies en créant des instances de la classe de base de PDO. Peut importe quel driver vous voulez utiliser ; vous utilisez toujours le nom de la classe PDO. Le constructeur accepte des paramètres pour spécifier la source de la base de données (connue en tant que DSN) et optionnellement, le nom d'utilisateur et le mot de passe (s'il y en a un).

Exemple 1. Connexion à MySQL
`<?php $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass); ?>`

S'il y a des erreurs de connexion, un objet PDOException est lancé. Vous pouvez attraper cette exception si vous voulez gérer cette erreur, ou laisser le gestionnaire global d'exception défini via la fonction set_exception_handler() la traiter.

Exemple 2. Gestion des erreurs de connexion
`<?php try { $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass); foreach ($dbh->query('SELECT * from FOO') as $row) { print_r($row); } $dbh = null; } catch (PDOException $e) { print "Erreur ! : " . $e->getMessage() . "<br/>"; die(); } ?>`

Avertissement
Si votre application n'attrape pas les exceptions lancées depuis le constructeur PDO, l'action par défaut du moteur zend est de terminer le script et d'afficher une trace. Cette trace devrait révéler des détails complets sur la connexion à la base de données, incluant le nom d'utilisateur et le mot de passe. Il en est donc de votre responsabilité d'attraper cette exception, soit explicitement (via l'instruction catch) ou implicitement via la fonction set_exception_handler().

Lorsque la connexion à la base de données a réussi, une instance de la classe PDO est retournée à votre script. La connexion est active tant que l'objet PDO l'est. Pour clore la connexion, vous devez détruire l'objet en vous assurant que toutes ses références sont effacées. Vous pouvez faire cela en assignant `NULL` à la variable gérant l'objet. Si vous ne le faites pas explicitement, PHP fermera automatiquement la connexion lorsque le script arrivera à la fin.

Exemple 3. Fermeture d'une connexion
`<?php $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass); // utiliser la connexion ici // et maintenant, fermez-la ! $dbh = null; ?>`

Beaucoup d'applications web utilisent des connexions persistantes aux serveurs de base de données. Les connexions persistantes ne sont pas fermées à la fin du script, mais sont mises en cache et réutilisées lorsqu'un autre script demande une connexion en utilisant les mêmes paramètres. Le cache des connexions persistantes vous permet d'éviter d'établir une nouvelle connexion à chaque fois qu'un script doit accéder à une base de données, rendant l'application web plus rapide.

Exemple 4. Connexions persistantes
`<?php $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass, array( PDO::ATTR_PERSISTENT => true )); ?>`

> Note : Si vous utilisez le driver PDO ODBC et que votre bibliothèque ODBC supporte le pool de connexion ODBC (unixODBC et Windows le supportent tous les deux ; peut être plus), alors il est recommandé de ne pas utiliser les connexions persistantes PDO mais plutôt laisser le pool de connexion ODBC mettre en cache les connexions. Le pool de connexion ODBC est partagé avec les autres modules dans le processus ; si PDO met en cache la connexion, alors cette connexion ne sera jamais retournée par le pool de connexion ODBC, faisant que plusieurs connexions sont créées pour les autres modules.

# Transactions et validation automatique (auto-commit)

Maintenant que vous êtes connecté via PDO, vous devez comprendre comment PDO gère les transactions avant d'exécuter des requêtes. Si vous n'avez jamais utilisé les transactions, elles offrent 4 fonctionnalités majeures : Automatisme, Consistance, Isolation et Durabilité (ACID). En d'autres termes, n'importe quel travail mené à bien dans une transaction, même s'il est effectué par étapes, est garanti d'être appliqué à la base de données sans risque, et sans interférence pour les autres connexions, quand il est validé. Le travail des transactions peut également être automatiquement annulé à votre demande (en supposant que vous n'avez encore rien validé), ce qui rend la gestion des erreurs bien plus simple dans vos scripts.

Les transactions sont typiquement implémentées pour appliquer toutes vos modifications en une seule fois ; ceci a le bel effet d'éprouver drastiquement l'efficacité de vos mises à jour. Dans d'autres termes, les transactions rendent vos scripts plus rapides et potentiellement plus robustes (vous devez les utiliser correctement pour avoir ces bénéfices).

Malheureusement, toutes les bases de données ne supportent pas les transactions, donc, PDO doit s'exécuter en mode "auto-commit" lorsque vous ouvrez pour la première fois la connexion. Le mode "auto-commit" signifie que toutes les requêtes que vous exécutez ont leurs transactions implicites, si la base de données le supporte ou aucune transaction si la base de données ne les supporte pas. Si vous avez besoin d'une transaction, vous devez utiliser la méthode PDO::beginTransaction() pour l'initialiser. Si le driver utilisé ne supporte pas les transactions, une exception PDO sera lancée (en accord avec votre gestionnaire d'erreurs : ceci est toujours une erreur sérieuse). Une fois que vous êtes dans une transaction, vous devez utiliser la fonction PDO::commit() ou la fonction PDO::rollBack() pour la terminer, suivant le succès de votre code durant la transaction.

Lorsque le script se termine ou lorsque la connexion est sur le point de se fermer, si vous avez une transaction en cours, PDO l'annulera automatiquement. Ceci est une mesure de sécurité afin de garantir la consistance de vos données dans le cas où le script se termine d'une façon inattendue. Si vous ne validez pas explicitement la transaction, alors, on présume que quelque chose s'est mal passé et l'annulation de la transaction intervient afin de garantir la sécurité de vos données.

Avertissement
L'annulation automatique intervient si vous avez initialisé la transaction via PDO::beginTransaction(). Si vous avez manuellement exécuté une requête qui commence une transaction, PDO n'a aucun moyen de le savoir et donc, n'annulera pas automatiquement cette transaction si quelque chose s'est mal passé.

Exemple 5. Exécution d'un groupe dans une transaction Dans l'exemple suivant, supposons que nous allons créer un jeu d'entrées pour un nouvel employé, dont le numéro d'ID sera 23. En plus des données basiques sur cette personne, nous devons également lui enregistrer son salaire. Il est très simple d'effectuer deux mises à jour séparées, mais en les enfermant dans les appels des fonctions PDO::beginTransaction() et PDO::commit(), nous garantissons que personne ne pourra voir ces modifications tant qu'elles ne seront pas complètes. Si quelque chose tourne mal, le bloc de capture annulera toutes les modifications effectuées depuis le début de la transaction et affichera un message d'erreur.
`<?php try { $dbh = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2', array(PDO::ATTR_PERSISTENT => true)); echo "Connecté\n"; $dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION); $dbh->beginTransaction(); $dbh->exec("insert into staff (id, first, last) values (23, 'Joe', 'Bloggs')"); $dbh->exec("insert into salarychange (id, amount, changedate) values (23, 50000, NOW())"); $dbh->commit(); } catch (Exception $e) { $dbh->rollBack(); echo "Échec : " . $e->getMessage(); } ?>`

Vous n'êtes pas limité dans le nombre de mises à jour dans une transaction ; vous pouvez également y effectuer des requêtes complexes et bien sûr, utiliser ces informations pour construire d'autres mises à jour et requêtes ; durant l'activité de la transaction, vous êtes garanti que personne d'autre ne peut effectuer des modifications alors que vous êtes au milieu de vos modifications. En réalité, ceci n'est pas 100% correct, mais cela reste une très bonne introduction aux transactions.

# Requêtes préparées et procédures stockées

La plupart des bases de données supportent le concept des requêtes préparées. Qu'est-ce donc ? Vous pouvez les voir comme une sorte de modèle compilé pour le SQL que vous voulez exécuter, qui peut être personnalisé en utilisant des variables en guise de paramètres. Les requêtes préparées offrent deux fonctionnalités essentielles :

- La requête ne doit être analysée (ou préparée) qu'une seule fois, mais peut être exécutée plusieurs fois avec des paramètres identiques ou différents. Lorsque la requête est préparée, la base de données va analyser, compiler et optimiser son plan pour exécuter la requête. Pour les requêtes complexes, ce processus peut prendre assez de temps, ce qui peut ralentir vos applications si vous devez répéter la même requête plusieurs fois avec différents paramètres. En utilisant les requêtes préparées, vous évitez ainsi de répéter le cycle analyser/compilation/optimisation. Pour résumer, les requêtes préparées utilisent moins de ressources et s'exécutent plus rapidement.

- Les paramètres pour préparer les requêtes n'ont pas besoin d'être entre guillemets ; le driver le gère pour vous. Si votre application utilise exclusivement les requêtes préparées, vous pouvez être sûr qu'aucune injection SQL n'est possible (Cependant, si vous construisez d'autres parties de la requête en vous basant sur des entrées utilisateurs, vous continuez à prendre un risque).

Les requêtes préparées sont tellement pratiques que c'est l'unique fonctionnalité que PDO émule pour les drivers qui ne les supportent pas. Ceci assure de pouvoir utiliser la même technique pour accéder aux données, sans se soucier des capacités de la base de données.

Exemple 6. Insertions répétitives en utilisant les requêtes préparées Cet exemple effectue une requête INSERT en y substituant un nom et une valeur pour les marqueurs nommés.
`<?php $stmt = $dbh->prepare("INSERT INTO REGISTRY (nom, valeur) VALUES (:nom, :valeur)"); $stmt->bindParam(':nom', $nom); $stmt->bindParam(':valeur', $valeur); // insertion d'une ligne $nom = 'one'; $valeur = 1; $stmt->execute(); // insertion d'une autre ligne avec des valeurs différentes $nom = 'two'; $valeur = 2; $stmt->execute(); ?>`

Exemple 7. Insertions répétées en utilisant des requêtes réparées Cet exemple effectue une requête INSERT en y substituant un nom et une valeur pour les marqueurs ?.
`<?php $stmt = $dbh->prepare("INSERT INTO REGISTRY (nom, valeur) VALUES (?, ?)"); $stmt->bindParam(1, $nom); $stmt->bindParam(2, $valeur); // insertion d'une ligne $nom = 'one'; $valeur = 1; $stmt->execute(); // insertion d'une autre ligne avec différentes valeurs $nom = 'two'; $valeur = 2; $stmt->execute(); ?>`

Exemple 8. Récupération des données en utilisant des requêtes préparées Cet exemple récupère des données basées sur la valeur d'une clé fournie par un formulaire. L'entrée utilisateur est automatiquement échappée, il n'y a donc aucun risque d'attaque par injection SQL.
`<?php $stmt = $dbh->prepare("SELECT * FROM REGISTRY where nom = ?"); if ($stmt->execute(array($_GET['nom']))) { while ($row = $stmt->fetch()) { print_r($row); } } ?>`

Si le driver de la base de données le supporte, vous pouvez également lier des paramètres aussi bien pour l'entrée que pour la sortie. Les paramètres de sortie sont utilisés typiquement pour récupérer les valeurs d'une procédure stockée. Les paramètres de sortie sont un peu plus complexe à utiliser que les paramètres d'entrée car vous devez savoir la longueur d'un paramètre donné pourra atteindre lorsque vous le liez. Si la valeur retournée est plus longue que la taille qui vous auriez suggéré, une erreur sera émise.

Exemple 9. Appel d'une procédure stockée avec un paramètre de sortie
`<?php $stmt = $dbh->prepare("CALL sp_returns_string(?)"); $stmt->bindParam(1, $return_value, PDO::PARAM_STR, 4000); // Appel de la procédure stockée $stmt->execute(); print "La procédure a retourné : $return_value\n"; ?>`

Vous devez également spécifier les paramètres qui gèrent les valeurs aussi bien pour l'entrée que pour la sortie ; la syntaxe est similaire aux paramètres de sortie. Dans le prochain exemple, la chaîne 'Bonjour' est passée à la procédure stockée et lorsqu'elle retourne la valeur, 'Bonjour' est remplacée par la valeur retournée par la procédure.

Exemple 10. Appel d'une procédure stockée avec un paramètre d'entrée/sortie
`<?php $stmt = $dbh->prepare("CALL sp_takes_string_returns_string(?)"); $value = 'hello'; $stmt->bindParam(1, $value, PDO::PARAM_STR|PDO::PARAM_INPUT_OUTPUT, 4000); // appel de la procédure stockée $stmt->execute(); print "La procédure a retourné : $value\n"; ?>`

# Erreurs et gestionnaire des erreurs

PDO offre la possibilité de gérer les erreurs de 3 façons différentes, pour coller au mieux au style de votre application.

- `PDO::ERRMODE_SILENT`

  C'est le mode par défaut. PDO définit simplement le code erreur pour vous afin de l'inspecter en utilisant les méthodes PDO::errorCode() et PDO::errorInfo() sur la requête ou sur les objets de la base de données ; si l'erreur est issue d'un appel à un objet de requête, vous devriez invoquer les méthodes PDOStatement::errorCode() ou PDOStatement::errorInfo() sur cet objet. Si l'erreur est issue d'un appel sur un objet de la base de données, vous devriez invoquer à la place les méthodes de cet objet.

- `PDO::ERRMODE_WARNING`

  En plus de définir le code erreur, PDO émettra un message de niveau E_WARNING. Ce comportement est très utile lors de la phase de test/débogage, si vous voulez juste voir le problème qui survient sans pour autant stopper le flot de l'application.

- `PDO::ERRMODE_EXCEPTION`

  En plus de définir le code erreur, PDO lancera une exception PDOException et y définit ces propriétés pour refléter le code erreur et l'information sur l'erreur. Ce comportement est utile également durant la période de débogage car il va stopper l'application à l'endroit même de l'erreur et pointer l'endroit où se trouve potentiellement l'erreur dans votre code (souvenez-vous : les transactions sont automatiquement annulées si l'exception fait que le script se termine).

  Le mode lançant des exceptions est également utile pour structurer la gestion de vos erreurs plus clairement que par la traditionnelle gestion des erreurs de PHP et avec moins de code, plutôt que le mode silencieux et l'analyse explicite des valeurs retournées par chaque appel à la base de données.

  Lisez la documentation sur les exceptions pour plus de détails sur les exceptions en PHP.

PDO standardise les codes erreurs en utilisant SQL-92 SQLSTATE ; les drivers individuels PDO sont responsables du mapping de leurs propres codes avec les codes SQLSTATE appropriées. La méthode PDO::errorCode() retourne un seul code SQLSTATE. Si vous avez besoin de plus d'informations sur une erreur, PDO fournit également la méthode PDO::errorInfo() qui retourne un tableau contenant le code SQLSTATE, le code erreur spécifique du driver et la chaîne erreur spécifique au driver.

# Les objets larges (LOBs)

À un moment dans votre application, vous pourriez avoir besoin de stocker de larges données dans votre base de données. "Large" signifie typiquement des données d'environ 4ko ou plus, bien que certaines bases de données peuvent gérer plus de 32ko avant que les données deviennent "larges". Les objets larges peuvent être de nature textuelle ou binaire. PDO vous permet de travailler avec ce type de larges données en utilisant le code type `PDO::PARAM_LOB` dans vos appels aux fonctions PDOStatement::bindParam() ou PDOStatement::bindColumn(). `PDO::PARAM_LOB` demande à PDO de mapper les données en un flux que vous pourrez manipuler en utilisant l'API PHP sur les flux.

Exemple 11. Affichage d'une image depuis une base de données Cet exemple lie un LOB dans une variable nommée $lob et l'envoie au navigateur en utilisant la fonction fpassthru(). Étant donné qu'un LOB est représenté en un flux, les fonctions comme fgets(), fread() et stream_get_contents() peuvent être utilisées sur ce flux.
`<?php $db = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2'); $stmt = $db->prepare("select contenttype, imagedata from images where id=?"); $stmt->execute(array($_GET['id'])); $stmt->bindColumn(1, $type, PDO::PARAM_STR, 256); $stmt->bindColumn(2, $lob, PDO::PARAM_LOB); $stmt->fetch(PDO::FETCH_BOUND); header("Content-Type: $type"); fpassthru($lob); ?>`

Exemple 12. Insertion d'une image dans une base de données Cet exemple ouvre un fichier et passe le pointeur de fichier à PDO pour l'insérer en tant que LOB. PDO fera son possible pour récupérer le contenu du fichier et l'insérer dans la base de données de la manière la plus efficace possible.
`<?php $db = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2'); $stmt = $db->prepare("insert into images (id, contenttype, imagedata) values (?, ?, ?)"); $id = get_new_id(); // fonction pour allouer un nouvel ID // assumons que nous récupérons un fichier depuis un formulaire // vous pouvez trouver plus de détails dans la documentation de PHP $fp = fopen($_FILES['file']['tmp_name'], 'rb'); $stmt->bindParam(1, $id); $stmt->bindParam(2, $_FILES['file']['type']); $stmt->bindParam(3, $fp, PDO::PARAM_LOB); $stmt->beginTransaction(); $stmt->execute(); $stmt->commit(); ?>`

Exemple 13. Insertion d'une image dans une base de données Oracle Oracle requiert une syntaxe légèrement différente pour y insérer un LOB depuis un fichier. Il est également essentiel d'effectuer votre insertion au sein d'une transaction, sinon, votre nouveau LOB sera inséré avec une longueur de zéro :
`<?php $db = new PDO('oci:', 'scott', 'tiger'); $stmt = $db->prepare("insert into images (id, contenttype, imagedata) " . "VALUES (?, ?, EMPTY_BLOB()) RETURNING imagedata INTO ?"); $id = get_new_id(); // fonction pour allouer un nouvel ID // assumons que nous récupérons un fichier depuis un formulaire // vous pouvez trouver plus de détails dans la documentation de PHP $fp = fopen($_FILES['file']['tmp_name'], 'rb'); $stmt->bindParam(1, $id); $stmt->bindParam(2, $_FILES['file']['type']); $stmt->bindParam(3, $fp, PDO::PARAM_LOB); $stmt->beginTransaction(); $stmt->execute(); $stmt->commit(); ?>`

# Classes pré-définies

## PDO

Représente une connexion entre PHP et un serveur de base de données.

### Constructeur

- PDO - construit un nouvel objet PDO

### Méthodes

- beginTransaction - commence une transaction

- commit - valide une transaction

- errorCode - récupère un code erreur, s'il y en a, depuis la base de données

- errorInfo - récupère un tableau contenant les informations sur l'erreur, s'il y en a, depuis la base de données

- exec - exécute une requête SQL et retourne le nombre de lignes affectées

- getAttribute - récupère un attribut d'une connexion à une base de données

- lastInsertId - récupère la valeur de la dernière ligne insérée dans une table

- prepare - prépare une requête SQL pour exécution

- query - exécute une requête SQL et retourne le jeu de résultats

- quote - retourne une version protégée d'une chaîne pour utilisation dans une requête SQL

- rollBack - annule une transaction

- setAttribute - définit un attribut d'une connexion à une base de données

## PDOStatement

Représente une requête préparée et, après exécution de la requête, un jeu de résultat associatif.

### Méthodes

- bindColumn - lie une variable PHP à une colonne de sortie dans un jeu de résultats

- bindParam - lie une variable PHP à un paramètre dans une requête préparée

- bindValue - lie une valeur à un paramètre dans une requête préparée

- closeCursor - ferme le curseur, autorisant la requête à être exécutée une nouvelle fois

- columnCount - retourne le nombre de colonnes dans un jeu de résultats

- errorCode - récupère le code erreur, s'il y en a, depuis une requête

- errorInfo - récupère un tableau contenant les informations sur une erreur, s'il y en a, depuis une requête

- execute - exécute une requête préparée

- fetch - récupère une ligne depuis un jeu de résultats

- fetchAll - récupère un tableau contenant toutes les lignes depuis un jeu de résultats

- fetchColumn - retourne les données depuis une colonne d'un jeu de résultats

- getAttribute - récupère un attribut PDOStatement

- getColumnMeta - récupère les méta-informations pour une colonne d'un jeu de résultats

- nextRowset - récupère la ligne suivante (du jeu de résultats)

- rowCount - retourne le nombre de lignes affectées par l'exécution d'une requête SQL

- setAttribute - définit un attribut PDOStatement

- setFetchMode - définit le mode de récupération pour une PDOStatement

## PDOException

Représente une erreur émise par PDO. Vous ne devriez pas lancer une exception PDOException depuis votre propre code. Lisez la documentation sur les Exceptions pour plus de détails sur les exceptions en PHP.

Exemple 14. La classe PDOException
`<?php class PDOException extends Exception { public $errorInfo = null; // correspond à PDO::errorInfo() // ou PDOStatement::errorInfo() protected $message; // message d'erreur textuel // utiliser Exception::getMessage() pour y accéder protected $code; // code erreur SQLSTATE // utiliser Exception::getCode() pour y accéder } ?>`

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

Avertissement
PDO utilise les constantes de classe depuis PHP 5.1. Les versions antérieures utilisent les constantes globales sous la forme `PDO_PARAM_BOOL`.

`PDO::PARAM_BOOL` (entier)

  Représente le type de données booléen.

`PDO::PARAM_NULL` (entier)

  Représente le type de données NULL SQL.

`PDO::PARAM_INT` (entier)

  Représente le type de données INTEGER SQL.

`PDO::PARAM_STR` (entier)

  Représente les types de données CHAR, VARCHAR ou les autres types de données sous forme de chaîne de caractères SQL.

`PDO::PARAM_LOB` (entier)

  Représente le type de données "objet large" SQL.

`PDO::PARAM_STMT` (entier)

  Représente un type de jeu de résultats. N'est actuellement pas supporté par tous les drivers.

`PDO::PARAM_INPUT_OUTPUT` (entier)

  Spécifie que le paramètre est un paramètre INOUT pour une procédure stockée. Vous devez utiliser l'opérateur OR avec un type de données explicite PDO::PARAM_*.

`PDO::FETCH_LAZY` (entier)

  Spécifie que la méthode de récupération doit retourner chaque ligne en tant qu'objet avec les noms de variables correspondant aux noms des colonnes retournées dans le jeu de résultats. PDO::FETCH_LAZY crée les noms des variables de l'objet comme ils sont rencontrés.

`PDO::FETCH_ASSOC` (entier)

  Spécifie que la méthode de récupération doit retourner chaque ligne dans un tableau indexé par les noms des colonnes comme elles sont retournées dans le jeu de résultats correspondant. Si le jeu de résultats contient de multiples colonnes avec le même nom, PDO::FETCH_ASSOC retourne une seule valeur par nom de colonne.

`PDO::FETCH_NAMED` (entier)

  Spécifie que la méthode de récupération doit retourner chaque ligne dans un tableau indexé par les noms des colonnes comme elles sont retournées dans le jeu de résultats correspondant. Si le jeu de résultats contient de multiples colonnes avec le même nom, PDO::FETCH_NAMED retourne un tableau de valeurs par nom de colonne.

`PDO::FETCH_NUM` (entier)

  Spécifie que la méthode de récupération doit retourner chaque ligne dans un tableau indexé par le numéro des colonnes comme elles sont retournées dans le jeu de résultats correspondant, en commençant à 0.

`PDO::FETCH_BOTH` (entier)

  Spécifie que la méthode de récupération doit retourner chaque ligne dans un tableau indexé par les noms des colonnes ainsi que leurs numéros, comme elles sont retournées dans le jeu de résultats correspondant, en commençant à 0.

`PDO::FETCH_OBJ` (entier)

  Spécifie que la méthode de récupération doit retourner chaque ligne dans un objet avec les noms de propriétés correspondant aux noms des colonnes comme elles sont retournées dans le jeu de résultats.

`PDO::FETCH_BOUND` (entier)

  Spécifie que la méthode de récupération doit retourner `TRUE` et assigner les valeurs des colonnes du jeu de résultats dans les variables PHP auxquelles elles sont liées avec la méthode PDOStatement::bindParam()() ou la méthode PDOStatement::bindColumn().

`PDO::FETCH_COLUMN` (entier)

  Spécifie que la méthode de récupération doit retourner uniquement une seule colonne demandée depuis la prochaine ligne du jeu de résultats.

`PDO::FETCH_CLASS` (entier)

  Spécifie que la méthode de récupération doit retourner une nouvelle instance de la classe demandée, liant les colonnes aux propriétés nommées dans la classe.

`PDO::FETCH_INTO` (entier)

  Spécifie que la méthode de récupération doit mettre à jour une instance existante de la classe demandée, liant les colonnes aux propriétés nommées dans la classe.

`PDO::FETCH_FUNC` (entier)

`PDO::FETCH_GROUP` (entier)

`PDO::FETCH_UNIQUE` (entier)

`PDO_ATTR_AUTOCOMMIT` (entier)

  Si la valeur vaut `FALSE`, PDO tente de désactiver l'auto-validation lorsque la connexion commence une transaction.

`PDO::ATTR_PREFETCH` (entier)

  Définir la taille de la pré-récupération vous permet d'accroître les performances de votre application. Toutes les combinaisons bases de données / drivers ne supportent pas cette fonctionnalité. Ceci accroît les performances au détriment de la consommation de mémoire vive.

`PDO::ATTR_TIMEOUT` (entier)

  Définit la valeur d'attente en secondes pour les communications avec la base de données.

`PDO::ATTR_ERRMODE` (entier)

  Voir la section sur les erreurs et la gestion des erreurs pour plus d'informations sur cet attribut.

`PDO::ATTR_SERVER_VERSION` (entier)

  Attribut en lecture seule ; il retourne des informations sur la version de la base de données à laquelle PDO est connecté.

`PDO::ATTR_CLIENT_VERSION` (entier)

  Attribut en lecture seule ; il retourne des informations sur la version de la bibliothèque cliente utilisée par PDO.

`PDO::ATTR_SERVER_INFO` (entier)

  Attribut en lecture seule ; il retourne quelques meta-informations sur le serveur de base de données auquel PDO est connecté.

`PDO::ATTR_CONNECTION_STATUS` (entier)

`PDO::ATTR_CASE` (entier)

  Force les noms des colonnes dans une casse spécifiée par les constantes PDO::CASE_*.

`PDO::ATTR_CURSOR_NAME` (entier)

  Récupère ou définit le nom à utiliser pour un curseur. Très utile lors de l'utilisation de curseurs scrollables et des mises à jour positionnées.

`PDO::ATTR_CURSOR` (entier)

  Sélectionne le type de curseur. PDO supporte actuellement soit `PDO::CURSOR_FWDONLY`, soit `PDO::CURSOR_SCROLL`. Conserver `PDO::CURSOR_FWDONLY` tant que vous savez que vous avez besoin d'un curseur scrollable.

`PDO::ATTR_DRIVER_NAME` (chaîne de caractères)

  Retourne le nom du driver.

  Exemple 15. Utilisation de PDO::ATTR_DRIVER_NAME
  `<?php if ($db->getAttribute(PDO::ATTR_DRIVER_NAME) == 'mysql') { echo "Utilisation de mysql ; fait quelque chose de spécifique à mysql ici\n"; } ?>`

`PDO::ATTR_ORACLE_NULLS` (entier)

  Convertit les chaînes vides en valeurs NULL SQL dans les données récupérées.

`PDO::ATTR_PERSISTENT` (entier)

  Demande une connexion persistante, plutôt que de créer une nouvelle connexion. Voir les connexions et le gestionnaire de connexion pour plus d'informations sur cet attribut.

`PDO::ATTR_FETCH_CATALOG_NAMES` (integer)

  Ajoute le contenu du catalogue de noms dans chaque nom de colonnes retourné dans le jeu de résultat. Le catalogue de noms et les noms de colonnes sont séparés par un point (.). Le support de cet attribut n'est pas disponible pour tous les drivers ; il peut ne pas être disponible pour votre driver.

`PDO::ATTR_FETCH_TABLE_NAMES` (integer)

  Ajoute le contenu de la table de noms dans chaque nom de colonne retourné dans le jeu de résultats. La table de nom et les noms de colonnes sont séparés par un point (.). Le support de cet attribut n'est pas disponible pour tous les drivers ; il peut ne pas être disponible pour votre driver.

`PDO::ERRMODE_SILENT` (entier)

  N'envoie pas d'erreur ni d'exception si une erreur survient. Le développeur doit explicitement vérifier les erreurs. C'est le mode par défaut. Voir les erreurs et la gestion des erreurs pour plus d'informations sur cet attribut.

`PDO::ERRMODE_WARNING` (entier)

  Envoie une erreur de niveau E_WARNING si une erreur survient. Voir les erreurs et la gestion des erreurs pour plus d'informations sur cet attribut.

`PDO::ERRMODE_EXCEPTION` (entier)

  Lance une exception PDOException si une erreur survient. Voir les erreurs et la gestion des erreurs pour plus d'informations sur cet attribut.

`PDO::CASE_NATURAL` (entier)

  Laisse les noms de colonnes comme retournés par le driver de base de données.

`PDO::CASE_LOWER` (entier)

  Force les noms de colonnes en minuscule.

`PDO::CASE_UPPER` (entier)

  Force les noms des colonnes en majuscule.

`PDO::FETCH_ORI_NEXT` (entier)

  Récupère la prochaine ligne d'un jeu de résultats. Valide seulement pour les curseurs scrollables.

`PDO::FETCH_ORI_PRIOR` (entier)

  Récupère la ligne précédente d'un jeu de résultats. Valide seulement pour les curseurs scrollables.

`PDO::FETCH_ORI_FIRST` (entier)

  Récupère la première ligne d'un jeu de résultats. Valide seulement pour les curseurs scrollables.

`PDO::FETCH_ORI_LAST` (entier)

  Récupère la dernière ligne d'un jeu de résultats. Valide seulement pour les curseurs scrollables.

`PDO::FETCH_ORI_ABS` (entier)

  Récupère la ligne demandée par un numéro de ligne d'un jeu de résultats. Valide seulement pour les curseurs scrollables.

`PDO::FETCH_ORI_REL` (entier)

  Récupère la ligne demandée par une position relative à la position courante du curseur d'un jeu de résultats. Valide seulement pour les curseurs scrollables.

`PDO::CURSOR_FWDONLY` (entier)

  Crée un objet PDOStatement avec un curseur uniquement de retour. C'est le choix par défaut pour le curseur, car il est rapide et l'accès aux données est commun pour les masques en PHP.

`PDO::CURSOR_SCROLL` (entier)

  Crée un objet PDOStatement avec un curseur scrollable. Passez la constante PDO::FETCH_ORI_* pour contrôler les lignes récupérées du jeu de résultats.

`PDO::ERR_NONE` (chaîne de caractères)

  Correspond à SQLSTATE '00000', ce qui signifie que la requête SQL a réussi sans erreur, ni avertissement. Cette constante est utile lorsque vous utilisez PDO::errorCode() ou PDOStatement::errorCode() pour déterminer si une erreur est survenue. Cependant, vous devez déjà savoir si c'est le cas en examinant le code retourné par la méthode qui a lancée l'erreur.

Précédent | Sommaire | Suivant
pdf_xshow | Niveau supérieur | PDO::beginTransaction